Outubro é mês de hacktoberfest e esse deve ser o mês em que nós nos esforçamos mais para contribuir com open-source e ajudar a mais pessoas contribuírem. Então nesse artigo você vai aprender cinco 5 dicas de ouro para fazer o seu pull request ✨ brilhar ✨. Vamos lá!

Siga o guia de contribuição do projeto

A maioria dos projetos open-source tem um conjunto de regras ou padrões que você deve seguir para contribuir, coisas como manter cobertura de testes, criar branches seguindo um certo padrão de nomeação, qual a língua oficial do projeto e de seus commits e até mesmo regras sobre intervalo de tempo com inatividade no qual passado esse períodos o pull requests sem atividade será fechado.

Seguir o guia do projeto vai garantir um bom caminho para ter um pull request bem sucedido logo do começo, esse guia é geralmente encontrado no arquivo CONTRIBUTING.md nos projetos do GitHub mas por vezes as regras também podem estar descritas no arquivo README.md.

Agora você pode estar se perguntando “O que eu faço se o projeto não tiver um guia de contribuição?” e essa situação é bem comum. Então caso não exista um guia de contribuição o que eu faço geralmente é olhar alguns commits do histórico de commits para ver como eles são feitos e outros pull requests que foram feitos antes do meu para tentar seguir o mesmo formato.

Use branches no seu fork

Ao fazer um fork de um projeto para contribuir, é muito comum cairmos no erro de fazer alterações no branch principal e submeter o pull request.

Evite.

Por mais que você só planeje fazer apenas um pull request, pode ser que a inspiração role e você queira fazer um segundo pull request e aí você já comprometeu o seu branch principal com alterações do primeiro pull request e, qualquer contribuição a partir desse ponto vai conter as alterações do primeiro pull request.

Então o ideal é manter o branch principal limpo de alterações até para que você possa mantê-lo atualizado com o branch principal do repositório de origem. Então crie o bom hábito de separar suas contribuições em branches novas.

Relacione o pull request com uma issue

Existem hoje 9 palavras-chave para relacionar o seu pull request com uma issue (se ela existir). Isso mesmo, nove! Usar essas palavras ao fazer o pull request vai facilitar a vida de quem mantém o projeto, pois essas palavras fecham a issue correspondente ao rolar o merge do pull request, e também vai ajudar pessoas que estejam interessadas em contribuir pois elas podem ver o pull request em andamento evitando que duas pessoas façam trabalho duplicado.

Então essa é a lista de palavras:

  1. close
  2. closes
  3. closed
  4. fix
  5. fixes
  6. fixed
  7. resolver
  8. resolve
  9. resolved

Essas palavras podem ser usadas em dois lugares:

  1. No título do pull request;
  2. Ou na descrição do pull request.

Você deve usá-las da seguinte forma para resolver uma issue:

fixes #42

Ou da forma a seguir para resolver mais de um issue:

fixes #42, fixes #44

Caso o seu pull request, não resolva uma issue por completo, você ainda deve mencionar o número da issue que tem relação com o seu pull request pois isso vai fazer que o seu pull request apareça na issue como uma menção, mas nesse caso não deve usar as palavras acima.

Como uma pessoa que mantem alguns projetos, me faz muito feliz ver essas palavras sendo usadas nos pull requests. Você pode ler mais sobre isso nessa documentação do próprio GitHub sobre o assunto.

Dê contexto para quem vai revisar

Muitas vezes as pessoas que mantêm projetos, assim como as pessoas que contribuem com projetos, fazem isso no seu tempo livre, ou seja, esse não é o trabalho delas. Então é nosso dever facilitar a contribuição, tanto ao escrever issues bem descritas se você estiver relatando um bug por exemplo, como descrever bem o pull request que você está fazendo. Vamos focar no pull request que é o foco deste artigo.

Hoje em dia é muito comum encontrar projetos que tenham um template/modelo de pull request, esse template busca padronizar as perguntas necessárias para a revisão daquele pull request e a geração de changelogs. Então foque no que você precisa preencher e lembre-se que é possível usar o markdown para estilizar o conteúdo da descrição e facilitar a leitura das pessoas que revisam as contribuições.

Embora hoje em dia vários repositórios tenham templates de pull request, pode ser que você está contribuindo para um projeto que não tem um desses, então aqui vai um lista de tópicos para você incluir na descrição do seu pull request:

  1. Qual o objetivo desse pull request?

    Aqui coloque aquela informação de qual issue (se ela existir) se relaciona com esse pull request.

  2. Quais alterações foram feitas para atingir esse objetivo?

    Alterações de código, documentação, mudanças de fluxo de dados e afins devem vir aqui. Use os seus commits para relembrar o que você mudou.

  3. Como testar se essas mudanças realmente funcionam?

    Aqui pode usar prints se for algo visual, por exemplo, ou exemplos de uso do pedaço de código novo.

  4. Possíveis melhorias e outras anotações

    Uma lista de coisas que poderiam ser melhoradas, mas que não são o foco do pull request, ou que você não sabe como resolver e precisa de ajuda.

Esses quatro pontos, vão garantir que a pessoa revisando vai ter todas informações que ela precisa para revisar o pull request no momento que a revisão for acontecer.

Aguarde as sugestões

Depois de fazer a sua contribuição a pessoa revisora pode ter sugestões de melhoria ou ajustes necessários para garantir a padronização da base de código. Essas sugestões podem pedir que você mude parte de código, implemente testes ou ajuste a documentação.

De um modo geral elas vêm para ajudar o seu pull request melhorar e para que a sua contribuição seja aceita. O processo de revisão é sempre um momento de aprendizado então é importante ter a mente aberta para receber sugestões e caso necessário acatá-las.

Recapitulando

Contribuir com open-source é ótimo pois pode ajudar todas as pessoas que usam aquele projeto. E durante o hacktoberfest, por exemplo, é um ótimo momento para exercitar essa habilidade, então não deixe de seguir as dicas que você viu aqui para ter ainda mais sucesso no seus pull requests.

Ah e último recadinho, se você estiver procurando por projetos brasileiros para contribuir aqui está a lista de 2021.