Guia de contribuição

Contribuindo com projetos Senior

Adoramos sua opinião! Queremos tornar a contribuição para este projeto o mais fácil e transparente possível, seja:

  • Relatando um bug
  • Discutindo o estado atual do código
  • Enviando uma correção de bug
  • Implementando novas funcionalidades
  • Propondo novos recursos
  • Virando um maintainer do projeto

Desenvolvemos com github

Usamos o github para hospedar nossos fontes, rastrear problemas e solicitações de recursos, bem como aceitar pull requests.

Utilizamos Github Flow, então todas as alterações são via Pull Requests

Pull requests são a melhor maneira de propor alterações na base de código. Seus Pull requests são bem vindos:

  1. Faça um fork do repositório e crie seu branch a partir da master;
  2. Se você adicionou código que deve ser testado, adicione testes;
  3. Se você mudou as APIs, atualize a documentação;
  4. Certifique-se de que os testes passam;
  5. Certifique-se de que o seu código passa nos lints configurados no projeto;
  6. Altere o arquivo changelog.md especificando a alteração. Padrão keep a changelog.
  7. Crie um pull request desse fork;
  8. Crie uma issue para esse pull request.

Contribuições sob Licença de Software MIT

Resumindo, quando você envia alterações de código, seus envios serão considerados sob a mesma Licença MIT que cobre o projeto. Sinta-se à vontade para contatar os maintainers se isso for uma preocupação.

Reporte bugs utilizando o Github’s issues

Usamos o Github’s issues para rastrear bugs. Abra um bug é bem fácil! Exemplos:

Especifique bem os bug reports com detalhes, históricos e amostra de códigos

Ótimos bugs reports costumam a ter:

  • Um resumo rápido e/ou histórico do problema
  • Passos para reproduzir o problema/erro
    • Seja bem específico!
    • Mostre e forneça a amostra de código que gera o problema/erro, se puder. Entenda que com essa amostra de código qualquer pessoa pode simular o erro, ou seja, especifique o setup, a base e tudo que for possível para ser fácil reprodução
  • O que você esperava que acontecesse
  • O que realmente aconteceu
  • Notas (incluindo por que você acha que isso pode estar acontecendo ou coisas que você tentou fazer para resolver e não funcionaram)

[Maintainers] – Revisando e mergeando PRs

Cada pull request deve ser revisado por um ou mais maintainers. Utilize o recurso de revisão de pull requests do Github. Resumindo, você deve enviar seu review com o status de “approved” ou “Request changes” para que o colaborador saiba quais são as próximas etapas.

Ao revisar um pull request, adicione labels de categorização (“bugfix”, “enhacement”, “feature”, etc…) para facilitar a identificação do pull request. Labels de release (“major”, “minor” e “patch”) devem ser utilizados para identificar qual o nível de alteração, e assim, sendo utilizado futuramente pelo CI/CD para liberar novas versões.

Ao realizar um merge de um pull request, certifique-se de que o build e testes daquele branch está sendo executado e passando corretamente. Utilize Squash commits ao realizar um merge de um pull request. Isso facilita a visão geral do branch master contendo apenas commits de merge de pull request. 

[Maintainers] – Liberando novas versões

Todos os projetos Github da Senior possuem um padrão de liberação baseado no Github’s Releases. Em geral, para nós cada release é uma tag e cada tag é uma versão liberada. Para fazer isso nós temos o seguinte fluxo:

  1. Define a nova versão a ser liberada com base nas versões já liberadas;
  2. Cria uma Release Draft, com o conteúdo do changelog;
  3. Faz alterações de versão de pacotes e arquivos de changelog;
  4. Libera a release criada como draft anteriormente;
  5. Publica a versão com base na tag.

Ok, bem legal, mas eu preciso fazer isso manualmente?

Não!! Nós temos um CI/CD configurado para fazer o trabalho sujo para nós. 

CI/CD para liberação de versão

Para cada commit na master do projeto nosso CI atualiza o release draft do projeto com o conteúdo do changelog.md. Com isso quem tiver fazendo a liberação deve utilizar aquele draft para fazer a publicação da release. Siga os passos abaixo para fazer a publicação:

  1. Acesse o projeto no Github;
  2. Acesse a página de releases clicando no link “Releases”, conforme destacado em vermelho na imagem abaixo:
    Clique em Releases
  3. Procure o draft e edite ele clicando no botão “Edit”. Imagem abaixo mostra a flag “draft” destacada em verde e o botão edit destacado em vermelho:
    Edite o release draft
  4. Revise a release e se estiver tudo certo publique a release clicando no botão “Publish release”, conforme destacado em vermelho na imabem abaixo:
    Clique no botão publish release no inferior da tela

Licença

Ao contribuir, você concorda que suas contribuições serão licenciadas sob a Licença MIT.

Referências

Este documento foi adaptado para as diretrizes de contribuição open-source do documento Facebook’s Draft