Mais de 10 coisas para fazer antes de solicitar reviso do seu Pull Request

Se voc est trabalhando em um time, abrir um Pull/Merge Request muito comum. No entanto, voc j pensou em abrir um Pull/Merge Request quando est trabalhando sozinho?

Isso pode parecer sem sentido, mas eu acho que uma excelente prtica! Voc pode se beneficiar de diversas formas ao revisar seu prprio Pull/Merge Request.

sempre bom contar com os colegas para revisar seu cdigo e encontrar trechos que passaram batido por voc ou seu pair, alm de compartilhar conhecimento com voc. No importa se voc trabalha sozinho ou com um time, eu recomendo seguir esse checklist:

1. Utilize o branch alvo correto

Vamos comear pelo mais fcil e rpido: verifique se o branch alvo que seu PR vai ser mergeado, est correto.

Se voc sempre se perde na hora de abrir o PR pela interface web no GitHub, eu recomendo dar uma olhada no GitHub CLIou noHub.
Ambos permitem voc abrir o PR direto no seu terminal, especificando o branch base (que ser o seu alvo):

$ hub pull-request -b meu-branch-alvo

Esse comando vai abrir o editor definido na varivel ambiente $EDITOR, voc s precisar definir o ttulo do PR e a descrio.

Ou se preferir, utilizando a ferramenta mais recente do GitHub (GitHub CLI gh):

$ gh pr create -b meu-branch-alvo

Esse comando vai te perguntar direto no terminal quais so os metadados do PR.

2. Mostre seu rascunho

Eu j vi diversas pessoas desenvolvedoras abrindo PRs apenas quando o trabalho est quase pronto (ou at s quando est pronto). Eu recomendo abrir os PRs em Draftlogo depois de fazer o primeiro commit. Isso permite acompanhar seu progresso e alimentar ferramentas de mtricas de cdigo (como a SourceLevel), alm de obter feedback do seu time antes da sua soluo estar pronta.

Quando for escrever uma descrio, faa uma pequena checklist para deixar explcito o quanto voc avanou naquela soluo. Eu gosto bastante dessa ideia porque ela deixa muito mais claro o que voc precisa fazer como prximo passo e seus colegas tambm podem te apoiar caso j tenham feito algo parecido em um passo que esteja pendente.

Voc tambm pode utilizar o hub para abrir PRs direto em Draft com a opo -d:

$ hub pull-request -b meu-branch-alvo -d

E no gh:

$ gh pr create -b meu-branch-alvo -d

3. Vamos falar de cdigo!

Vamos assumir que voc abriu um PR em rascunho, mas e o cdigo? O que voc deve revisar antes de pedir para o seu time revisar?

Eu recomendo comear com os mais fceis sempre:

• Erros de digitao
• Notaes TODO ou NOTE
• Comentrios no cdigo
• Chamadas print/puts
• Linhas duplas em branco
• Espaos em branco no final de linhas ou de arquivos

Voc pode configurar seu editor para evitar esse ltimo item, procure por remove trailing spaces in <seu editor favorito>. Acredite em mim: isso economiza muito tempo ao salvar um arquivo e j remover esses espaos automaticamente.

4. D nomes apropriados

Algumas pessoas desenvolvedoras investem muito tempo nomeando mdulos, classes, variveis e assim por diante. Normalmente, eu comeo com um nome que parece bom e no final do ciclo de desenvolvimento eu o reviso, sempre aparecem melhores opes. Ento no se esquea de revisitar seu cdigo e nome-los devidamente.

Quando nomear as coisas, imagine que voc a "coisa" e se o nome que voc escolheu corresponde com a semntica do que voc est fazendo.

5. Pea ajuda de ferramentas

Seus colegas de trabalho no esto disponveis o tempo todo para voc ou at se voc trabalha sozinho, voc deveria se beneficiar de Linters! Eles podem ser muito mais teis que voc imagina!

Linters so ferramentas que analisam seu cdigo para identificar erros, warnings, convenes de estilo e questes de complexidade de cdigo. Por exemplo, no Ruby, existe oRubocop; noElixir, existe oCredo.

Usar linters uma forma excelente de reduzir e prevenir o dbito tcnico na sua base de cdigo. Comece com algumas regras e v adicionando conforme sentir necessidade no arquivo de configurao do linter.

No entanto, sempre lembre de discutir essas regras com seu time antes de se comprometer com elas. Evite falar sobre regras de linters em um Pull Request (a no ser que seja um PR dedicado a isso). Mova essa discusso para um lugar (como as issues) onde voc possa coletar feedback de mais membros do time e garantir que todos esto na mesma pgina e esto de acordo com aquela regra.

6. Remova o rudo

Quando estamos desenvolvendo, comum encontrar algum cdigo para refatorar, fazer aquele trabalho de jardinagem, utilizar o estilo de codificao da base de cdigo, ou remover aquele parnteses desnecessrio. Para esses casos, eu recomendo evitar fazer essa mudana se estiver fora do contexto do que voc est modificando.

Eu sei que muitas vezes difcil de evitar corrigir ou ajustar (j que aquele cdigo est logo ali), mas tenha em mente que voc sempre pode abrir um Pull Request separado para essas mudanas. E nele, explicar as razes e prover informaes adicionais porque aquela mudana necessria.

Por que fazer isso? Porque ao adicionar cdigo no-relacionado vai aumentar a complexidade para a pessoa revisora. Mais informaes fazem com que o processo seja mais detalhado e menos cdigo no-relacionado faz com que o processo de reviso seja mais preciso e mais focado no contexto exigido.

Se voc encontrar alguma modificao que fez durante o desenvolvimento e no queria descartar na hora de commitar, voc deveria dar uma olhada no comando git stash.

7. Traga apenas o necessrio do banco de dados

Se suas mudanas envolvem trazer dados do banco de dados, voc deveria especificar apenas as colunas que voc precisa. Pode ser caro sempre trazer dados que so irrelevantes para o seu uso do banco de dados. Tenha em mente que isso vai obrigar utilizar mais recursos na linguagem de programao utilizada tambm, como maior reteno de objetos/estruturas de dados, aumentando o consumo de memria da aplicao.

8. Entenda "Mergeabilidade"

Alguns PRs so mais fceis de mergear (integrar ao branch alvo) que os outros. Como definir se um PR aceitvel para ser mergeado?

Vrios times obrigam que os Pull Requests passem um conjuntos de verificaes para saber se eles esto elegveis para serem mergeados. Isso interessante para aumentar a confiabilidade da mudana que est sendo integrada e que no vai quebrar no branch alvo.

As verificaes normalmente incluem:

• Branches protegidos
• Obrigar reviso de cdigo
• Assinatura de commits via chaves GPG
• Histrico linear de alteraes
• Incluir status checks especficos, como build de testes

O ltimo item poderia ser obrigatrio: o commit status checks indicam se a ferramenta integrada (como o GitHub Actions ou alguma reviso de cdigo automatizada) passou a cada push . Voc pode configurar seu repositrio para obrigar cada um deles. Assim apenas push "verdes" esto bons para serem integrados no branch alvo!

Terminou?

Bom trabalho se voc chegou at aqui no seu checklist e seguiu todas as instrues. Agora hora dos ltimos e no menos importantes: melhorias nos metadados do Pull Request.

9. Passe a mensagem correta

Tudo que essencial deve ir para descrio do seu PR. Pense que essa descrio deve guiar os revisores sobre o contexto das mudanas, d o seu melhor para explicar porqu elas esto l.

Voc deve verificar todos os itens se voc abriu seu PR como Draft. Considere at transformar em um modelo para futuros Pull Requests. Se voc precisa de um modelo bem simples, recomendo utilizar o da SourceLevel.

Algumas outras coisas interessantes que voc pode incluir na descrio do PR:

• Instrues sobre "Como testar" aquelas mudanas
• O que no parte daquele PR (qualquer coisa no relacionada com o trabalho que voc gostaria que todos soubessem)
• O que pode ser melhorado no futuro (considere at criar uma issue e referenci-la no seu PR)
• Documentaes e referncias (lembre-se que PR tambm documentao e pode ser muito til para voc e seu time no futuro)
• Lista de referncias para issues existentes ou outros PRs (caso voc queira enriquecer ainda mais o contexto e deixar a base de PRs e issues cada vez mais rica com informaes)
• Snippets de cdigo de outros branches

10. Adicione screenshots

Screenshots so timas para mostrar como aquela mudana afeta o visual de uma pgina ou componente. Se voc possui mais de uma screenshot, considere utilizar uma seo com a tag <details>:

<details><summary>Screenshot oculta</summary>![alt text](https://example.com/image.png)</details>

Isso vai fazer com que a imagem fique escondida dessa maneira:

Sinta-se vontade para usar a tag <details> para um GIF ou um vdeo.

11. Encontre seu PR no futuro

Pessoas tendem a esquecer que elas podem consultar o histrico de PRs para tirar dvidas sobre como aquela funcionalidade ou bugfix foi construda e porqu. Se voc nunca olha um PR antigo em uma hora dessas, talvez voc esteja perdendo informaes teis.

J teve algum problema encontrando um PR especfico? Ento utilize labels melhores para classific-los. Precisa de sugesto de algumas? Tente essas:

• dependency
• documentation
• expedite
• feature
• good first patch
• ready for test, in test, test done
• security
• tech debt
• unplanned

Use sua criatividade para identificar labels atrativas que podem ajudar voc e seu time encontrar issues e PRs com elas.

12. Utilize comentrios inline nas suas prprias mudanas

Comente na linha ou trecho de cdigo qualquer fato interessante que voc sinta necessidade de compartilhar. Por exemplo, voc pode mencionar sobre aquele mtodo da API da linguagem de programao que voc acabou de descobrir, isso pode fazer vrias discusses interessantes surgirem, talvez at sugestes melhores.

isso a!

Parabns ! Fez alguma mudana no PR desde que voc tinha considerado ele como "Pronto" depois desse checklist?

Agora hora de fazer um rebase e garantir que est tudo atualizado e ento, finalmente, pronto para pedir reviso do seu time!

Obrigado pela leitura ;)

Voc aprendeu algo novo revisando o seu prprio cdigo? Compartilhe comigo!