Como criar um Pull Request perfeito

h√° 5 meses
Share this and help me to spread the word! ūü§ď

Grande parte do tempo em que trabalhamos de forma colaborativa estamos na verdade gastando nosso tempo com comunica√ß√£o. Seja via chat, e-mail, telefone ou as famigeradas reuni√Ķes.

Se você já leu o manifesto ágil deve se lembrar:

Indiv√≠duos e intera√ß√Ķes mais que processos e ferramentas

E ao contrário do que é dito popular: você é responsável pelo diz e de forma direta ou indireta; pelo que a outra parte entende.

Um pull request (ou merge request se você usa Gitlab) nada mais é do que uma declaração, uma mensagem ao seu time de que você terminou uma etapa do trabalho e precisa levar este trabalho adiante.

Ou seja: comunicação.

Code Review is the practice of having other peers reviewing source code changes before it gets introduced into a baseline. Developers usually review their team members' code, although there are companies that promote cross-team reviews.

https://sourcelevel.io/everything-about-code-review-from-peer-review-to-automated-code-review

Esta √© a import√Ęncia de um pull request bem feito.

Neste artigo veremos algumas dicas para criar pull requests que sejam realmente revisados e cumpram seu papel de gerar valor ao negócio; com código conciso, legível e testável.

Como escrever uma boa mensagem de commit?

A import√Ęncia da comunica√ß√£o eficiente que caracteriza um bom pull request come√ßa antes da cria√ß√£o do mesmo no Github, Gitlab, Bitbucket e similares.

√Č imprescind√≠vel que voc√™ escreva boas mensagens nos seus commits. Elas devem especificar exatamente o que foi feito e qual problema foi resolvido.

Novamente a dica óbvia dada acima: escreva bons commits. Não seja aquela pessoa que gera um commit com uma mensagem "WIP" e envia para o repositório remoto. Você não faz isso né? :P

Ensinar Git est√° fora do contexto deste artigo. Mas seguem algumas dicas

  • Evite o git add -a. Adicione apenas os arquivos que foram criados/alterados para aquela funcionalidade espec√≠fica
  • Fa√ßa commits pequenos
  • Revise as mensagens antes de fazer o push, ou seja, enviar a branch para o reposit√≥rio remoto
  • Se necess√°rio reescreva as mensagens. Para isto use comandos como git rebase -i e amend.
  • Aprenda a usar o git squash e agrupe commits que se encaixem em um mesmo contexto ou tenham sido altera√ß√Ķes repetitivas em um mesmo trecho de c√≥digo

Se você é um líder técnico combine as regras com o seu time, documente estas regras em um guideline e o mais importante: recuse pull requests que não as sigam.

Explique o propósito do pull request através do contexto de negócio

Agora se coloque no lugar daqueles que receberão a nobre tarefa de revisar o seu código. Tenha em mente que estas pessoas poderão estar em um contexto totalmente diferente daquele no qual você está quando abrir o pull request. Isto pode acontecer mesmo que os revisores e as revisoras estejam no mesmo projeto e no mesmo time.

Como mencionei acima, é importante se colocar no lugar das pessoas. Indo além, se coloque no lugar do seu "eu" do futuro e se pergunte se a descrição do pull request é clara o suficiente para que você a entenda 6 meses depois.

Explique o contexto de negócio do pull request. Como o problema foi identificado? Qual é o objetivo da funcionalidade?

Forne√ßa informa√ß√Ķes claras sobre como o revisor pode reproduzir o erro ou testar o c√≥digo que est√° sendo revisado e principalmente qual √© o resultado esperado e como isto pode gerar valor ao neg√≥cio.

Diminua o tamanho do pull request

O pull request perfeito deve ser pequeno. Se a funcionalidade que está sendo desenvolvida é muito grande ou complexa você poderá centralizar o trabalho em uma feature branch - a depender do fluxo de trabalho do time.

Lembre-se do SRP, ou Single Responsibility Principle e a assim como nos commits, faça pull requests pequenos.

5 formas de escrever t√≠tulos matadores. A √ļltima vai te surpreender!

Viram o bait?

Brincadeiras a parte. Escreva bons e - de preferência - pequenos títulos para seus pull requests.

Algumas dicas

  • Descreva o que foi feito ao inv√©s de como foi feito. A descri√ß√£o do pull request e o pr√≥prio c√≥digo devem mostrar o como
  • Utilize sempre o mesmo tom e tempo verbal
  • Fa√ßa uma conex√£o entre o t√≠tulo do pull request e o contexto de neg√≥cio

A descrição do pull request perfeito

Comece mostrando o contexto do problema/user story que est√° sendo implementado naquele pull request.

  • Utilize checklists e elementos visuais como captura de tela, gifs, snippets de c√≥digo, etc.
  • Justifique pontos que possam ser controversos e pol√™micos.
  • N√£o quebre janelas. Se o PR introduzir algum d√©bito t√©cnico demonstre o caso e se poss√≠vel como este d√©bito ser√° pago no futuro

Automatize tarefas repetitivas

As melhores plataformas do mercado contam com muitas ferramentas de verificação de status, tarefas pendentes e execução correta do pipeline de testes.

Voc√™ pode habilitar verifica√ß√Ķes de status obrigat√≥rias ou configurar merge checks no Bitbucket.

Desta forma, uma camada de verifica√ß√Ķes de integridade ser√° executada automaticamente durante o ciclo de vida do pull request.

Code Review - Pull request aberto? √Č hora da revis√£o

E atenção! Se liga aí, que é hora da revisão! (os xóvens provavelmente não pegaram a referência)

Como na vida, prevenir é melhor que remediar. O custo de descobrir bugs tarde é muito grande.

Pontos que devem ser observados com bastante atenção em um pull request

  • O c√≥digo funciona. Este √© √≥bvio, mas j√° vi muito pull request ser aprovado sem funcionar
  • Os testes est√£o bem escritos e descrevem claramente o que est√° sendo testado
  • O design e arquitetura est√£o bem definidos e em conformidade com as melhores pr√°ticas
  • Os guidelines est√£o sendo seguidos
  • O pull request pode introduzir alguma vulnerabilidade de seguran√ßa no c√≥digo ou atrav√©s de depend√™ncias?
  • A performance do software pode sofrer alguma queda

Algumas dicas para os revisores

  • Escreva coment√°rios tanto na descri√ß√£o geral do pull request
  • Crie checklists caso encontre m√ļltiplos pontos de melhoria ou esclarecimentos
  • Bom humor √© bem vindo! Mas n√£o utilize tom agressivo ou de deboche

Conclus√£o

Escrever o pull request perfeito pode ser um pouco trabalhoso no começo. Mas assim como em testes automatizados o investimento se paga no longo prazo! Pode confiar!

Referências