5 Dicas Para Fazer o Seu Pull Request Brilhar

Outubro ms de hacktoberfest e esse deve ser o ms em que ns nos esforamos mais para contribuir com open-source e ajudar a mais pessoas contriburem. Ento nesse artigo voc vai aprender cinco 5 dicas de ouro para fazer o seu pull request brilhar . Vamos l!

Siga o guia de contribuio do projeto

A maioria dos projetos open-source tem um conjunto de regras ou padres que voc deve seguir para contribuir, coisas como manter cobertura de testes, criar branches seguindo um certo padro de nomeao, qual a lngua oficial do projeto e de seus commits e at mesmo regras sobre intervalo de tempo com inatividade no qual passado esse perodos 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 comeo, esse guia geralmente encontrado no arquivo CONTRIBUTING.md nos projetos do GitHub mas por vezes as regras tambm podem estar descritas no arquivo README.md.

Agora voc pode estar se perguntando O que eu fao se o projeto no tiver um guia de contribuio? e essa situao bem comum. Ento caso no exista um guia de contribuio o que eu fao geralmente olhar alguns commits do histrico de commits para ver como eles so 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 alteraes no branch principal e submeter o pull request.

Evite.

Por mais que voc s planeje fazer apenas um pull request, pode ser que a inspirao role e voc queira fazer um segundo pull request e a voc j comprometeu o seu branch principal com alteraes do primeiro pull request e, qualquer contribuio a partir desse ponto vai conter as alteraes do primeiro pull request.

Ento o ideal manter o branch principal limpo de alteraes at para que voc possa mant-lo atualizado com o branch principal do repositrio de origem. Ento crie o bom hbito de separar suas contribuies 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 mantm o projeto, pois essas palavras fecham a issue correspondente ao rolar o merge do pull request, e tambm vai ajudar pessoas que estejam interessadas em contribuir pois elas podem ver o pull request em andamento evitando que duas pessoas faam trabalho duplicado.

Ento 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 ttulo do pull request;
2. Ou na descrio 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, no resolva uma issue por completo, voc ainda deve mencionar o nmero da issue que tem relao com o seu pull request pois isso vai fazer que o seu pull request aparea na issue como uma meno, mas nesse caso no 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 documentao do prprio GitHub sobre o assunto.

D contexto para quem vai revisar

Muitas vezes as pessoas que mantm projetos, assim como as pessoas que contribuem com projetos, fazem isso no seu tempo livre, ou seja, esse no o trabalho delas. Ento nosso dever facilitar a contribuio, 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 necessrias para a reviso daquele pull request e a gerao de changelogs. Ento foque no que voc precisa preencher e lembre-se que possvel usar o markdown para estilizar o contedo da descrio e facilitar a leitura das pessoas que revisam as contribuies.

Embora hoje em dia vrios repositrios tenham templates de pull request, pode ser que voc est contribuindo para um projeto que no tem um desses, ento aqui vai um lista de tpicos para voc incluir na descrio do seu pull request:

Qual o objetivo desse pull request?

Aqui coloque aquela informao de qual issue (se ela existir) se relaciona com esse pull request.

Quais alteraes foram feitas para atingir esse objetivo?

Alteraes de cdigo, documentao, mudanas de fluxo de dados e afins devem vir aqui. Use os seus commits para relembrar o que voc mudou.

Como testar se essas mudanas realmente funcionam?

Aqui pode usar prints se for algo visual, por exemplo, ou exemplos de uso do pedao de cdigo novo.

Possveis melhorias e outras anotaes

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

Esses quatro pontos, vo garantir que a pessoa revisando vai ter todas informaes que ela precisa para revisar o pull request no momento que a reviso for acontecer.

Aguarde as sugestes

Depois de fazer a sua contribuio a pessoa revisora pode ter sugestes de melhoria ou ajustes necessrios para garantir a padronizao da base de cdigo. Essas sugestes podem pedir que voc mude parte de cdigo, implemente testes ou ajuste a documentao.

De um modo geral elas vm para ajudar o seu pull request melhorar e para que a sua contribuio seja aceita. O processo de reviso sempre um momento de aprendizado ento importante ter a mente aberta para receber sugestes e caso necessrio 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, ento no deixe de seguir as dicas que voc viu aqui para ter ainda mais sucesso no seus pull requests.