Esse documento apresenta todas as informações necessárias para que possa colaborar com o projeto de forma independente.
Você pode contribuir de várias maneiras, sendo as mais conhecidas as seguintes:
- Localizando e relatando bugs
- Sugerindo melhorias
- Tirando dúvidas dos outros usuários
- Corrigindo bugs ou implementando novos recursos
- Melhorando a documentação
- Traduzindo a documentação
- Melhorando a estrutura do código
- Não tenha receio em contribuir se achar muito complexo as etapas para contribuir. Basta pedir apoio em issue ou PR e receberá auxílio no que precisar.
- Se está fazendo algum ajuste e está com dificuldades (Ex.: teste quebrando, dificuldade de criar novos testes, falta de entendimento de alguma regra de negócio, etc) também não tenha receios em pedir auxílio.
- Execução do projeto
- Etapas para contribuir
- Garantindo a qualidade do projeto
- Entrega contínua
- Documentação
- Reconhecimento de contribuição
É preciso ter os seguintes programas instalados:
- Git
- (opcional) Node.js, preferencialmente versão LTS.
- Se usar docker não será preciso instalar o Node
- Docker
- Docker compose
Docker e Docker-compose são utilizados para execução dos testes e do projeto
Com intuito de facilitar o desenvolvimento o projeto está todo dentro de container e sua execução é feita utilizando o arquivo Makefile.
Utilize o seguinte comando para executar o projeto enquanto desenvolve para utilizar a funcionalidade de reiniciar a aplicação a cada alteração:
make run-devPara realizar o debug da aplicação com VS Code há 2 maneiras:
- Debugando a aplicação em container Docker: Utilize o comando
make run-debuge na abaRun and Debugdo VS Code selecione a opçãoDocker: Attach to ServeRest container. - Debugando a aplicação localmente com NPM: Na aba
Run and Debugdo VS Code selecione a opçãoLaunch via NPM.
Escolha a forma de execução de acordo com o cenário que quer debugar.
Utilize a primeira opção se o erro ocorre em:
- Docker localmente.
- serverest.dev.
Utilize a segunda opção se o erro ocorre em:
- NPM localmente.
- Fork este repositório para sua própria conta GitHub, clone no seu computador e, em seguida, acesse o diretório criado;
- Faça as alterações necessárias;
- Faça o seu commit usando
npm run commit(opcional) - Envie um pull request;
- Aguarde o resultado das validações realizadas na integração contínua. Caso haja alguma quebra, analise e faça as correções necessárias.
Para o projeto manter a qualidade são feitas diversas validações, aonde é validado a estrutura do projeto, a imagem docker, teste das regras de negócio, contrato entre front e back, teste E2E em staging, teste de fumaça em produção, mensagem de commit, etc.
Todas essas etapas são muito importantes para que tenhamos confiança na qualidade das alterações com o mínimo de intervenção humana, permitindo rápida entrega do seu Pull Request para produção.
Aqui amamos automação, basta mergear o seu PR para a branch principal que a release será criada e totalmente validada.
Os testes são importantes para garantir a integridade do projeto a cada alteração realizada. É importante que atente de que a sua alteração necessite de novos testes ou adequação nos já existentes.
Os testes são executados com mocha, validados com chai, mockados com sinon.js e nock e as requests são feitas com supertest.
Para rodar os testes, execute:
make test-integrationpara os testes de integração.make test-e2e-localhostpara os testes E2E em cima da imagem docker que irá para produção.make test-unitpara os testes unitários.
Execute o comando make test para rodar os testes unitários e de integração.
O commit é abortado caso os testes unitários e de integração não resultem em sucesso
Usamos o nyc para validar a cobertura de código.
É importante que todo o código esteja com 100% de cobertura para podermos ter segurança que toda alteração no código será validada.
Para validar a cobertura localmente execute os testes. É apresentado um report no terminal informando a cobertura de todos os arquivos em /src. Se algum dos arquivos não estiver com 100% em todas as métricas crie os testes necessários.
Apenas os testes de integração e unitários possuem coleta de cobertura de código.
O teste de mutação garante que os testes de API são efetivos e complementa a cobertura de código.
A lib utilizada é a Stryker.
Para rodar os testes de mutação, execute o comando make test-mutation.
Para aprofundar sobre como funciona os testes de mutação, leia o meu texto 'Teste de mutação 👽: O que é e como fica a cobertura de código?'.
É utilizado o Terratest para realizar teste de infraestrutura, validando comportamento da imagem docker durante sua execução.
Para rodar o teste de infra e validar o docker build de produção, execute o comando make test-infra.
Para saber mais sobre teste de infraestrutura recomendo o texto What Is Infrastructure Testing And Why Is It Needed.
Usamos o standard como linter e formatter do código e lint-staged para forçar lint das alterações que estão em staged do git.
Execute npm run lint para padronizar os arquivos.
Execute npm run lint:fix para corrigir automaticamente os problemas encontrados pelo lint.
O commit é abortado caso esse padrão não seja seguido
As mensagens de commit devem seguir o padrão do conventional commit.
Para saber mais, acesse esses links:
Execute npm run commit para ter um painel interativo que permite seguir o padrão de commit de forma fácil.
O commit é abortado caso esse padrão não seja seguido
É utilizado o linter Hadolint - Haskell Dockerfile Linter para garantir que os Dockerfile de produção,desenvolvimento, teste e de teste de infra seguem as melhores práticas em sua estrutura.
A publicação de novas versões no NPM, no Docker e no serverest.dev é feita automaticamente após a execução com sucesso de todas as etapas da pipeline de entrega contínua.
É utilizada a lib Semantic-release com personalizações no arquivo .releaserc.js.
| NPM dist-tag | branch |
|---|---|
| @latest | trunk |
| @beta | beta |
Para ver todo o passo a passo da entrega contínua, como deploy em staging e produção, testes E2E em staging e produção e rollback automático se algum erro for detectado, acesse: https://github.com/ServeRest/ServeRest/actions/workflows/deploy-online-serverest.yml
Para aprofundar sobre como é feita a publicação do ServeRest, leia o texto 'Entrega contínua no ServeRest'. (desatualizado)
A documentação, disponibilizada nas URLs https://serverest.dev e http://localhost:3000, é editada no arquivo swagger.json.
Para atualizar:
- Acesse o arquivo swagger.json e o edite de acordo com sua necessidade.
- Execute o comando
make run-devpara acompanhar o status da documentação alterada na URL http://localhost:3000.
Todos aqueles que contribuíram com o projeto, independente do tipo de contribuição, devem ser reconhecidos.
Por isso, utilizamos o bot @all-contributors, que cria um Pull Request atualizando a seção de contribuidores no README.
Para entender como utilizar, basta acessar as intruções de uso do bot.