Pull request / Melhores práticas

Filipe — Mon, 31 Oct 2022 20:03:48 +0000

Por que se importar com bons pull requests?

Aumentar a produtividade do time
Minimizar a frustração

Também:

Um bom pull request tende a ser revisado rapidamente;
Reduz introdução de bugs na base de código;
Facilita a integração de novos desenvolvedores;
Não bloqueia o trabalho de outros devs;
Acelera o processo de revisão de código e consequentemente o desenvolvimento do produto.

Boas práticas:

Anatomia na criação de PRs

Target e source branches
feature/x --> development --> master
sourceㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤtarget
Tamanho
Evite PRs extensos. Procure abrir um pull request com poucos arquivos e linhas de código
Título e descrição
Forneça uma visão geral do seu trabalho juntamente com os links relevantes de forma que uma pessoa que acabou de entrar no time entenda.

Tenha em mente quando estiver recebendo ou dando feedback:

Um mesmo problema pode ter mais que uma boa solução. Discuta os tradeoffs (pros e contras), riscos, impacto e chegue à um consenso rapidamente.
Faça boas perguntas, não crie demandas. Boas perguntas evitam julgar a perspectiva do autor.
Não faça suposições, peça esclarecimentos.
Evite propriedade seletiva de código. ("meu", "não é meu", "seu" código)
Seja humilde e respeitoso para manter o ambiente real e profissional. De modo geral, evite termos que podem ser levados pro lado pessoal. Se emoji, GIFs ou humor não fazem o teu estilo, não force. Se fazem, use ~~e abuse~~.
Fale sincronamente (chat, compartilhando tela, pessoalmente) se você tem muitas dúvidas ou sugestões. Depois, faça um comentário resumindo a discussão.
Mencione colegas ou times que você queira envolver na discussão e mencione o porquê. (@fulano, tem alguma sugestão quanto à essa abordagem?)

Dando feedback:

Respeite o tempo da pessoa. Revise o mais rápido que puder. Seu colega pode iniciar outra tarefa e pode ser difícil para ele voltar à task do PR se você incluir alguns comentários.
Fique atento ao viés negativo (se o conteúdo é neutro, assumimos que o tom é negativo) na comunicação online. Sempre conceda feedbacks positivos. Evite linguagem negativa/neutra e prefira a positiva.

✅ Prefira:
"Eu sugiro X" ou "Você pode melhorar X fazendo Y"

❌ Evite: 
"Faz X" ou "X é errado, por que você não faz Z?"

Não mude o código enquanto estiver revisando.
Use uma checklist para tentar capturar algum deslize, erro, violação de convenção, risco de performance e etc.
Se você discorda fortemente, considere tirar alguns minutos para refletir antes de responder.
Explique os motivos pelo qual você acredita que o código deve ser alterado. Por exemplo: o código não está de acordo com o style guide ou até com uma preferência pessoal.
Forneça maneiras de simplificar ou aprimorar o código.
Se as discussões ficarem muito filosóficas ou acadêmicas, mova a discussão para uma reunião técnica relacionada ao assunto. Então, deixe o autor tomar a decisão final sobre as soluções alternativas.
Foque em desenvolver skills profissionais, conhecimento do grupo e a qualidade do produto, através da crítica coletiva.
Use emojis para esclarecer o tom. Compare "Parece bom :)" ou "Parece bom! 👍" com "Tá bom."

Respondendo feebacks:

Agradeça as sugestões. "Valeu! Vou alterar isso."
"Não leve pro pessoal. O que está sendo revisado é o seu código, não você". Assuma que o revisor teve a melhor intenção em seus comentários e tenha em mente o quão difícil é transmitir emoções online.
Explique a razão do código existir. "Fiz desse jeito, por causa disso, disso e disso. Seria mais claro se eu renomeasse essa classe/arquivo/método/variável?".
Caso encontre possibilidade de mudança ou refatoração, registre-as em tasks futuras e histórias.
Tente responder todos os comentários.
Se perceber alguma confusão ou debate começando, se pergunte se o que você escreveu foi escrito da melhor maneira. Converse (virtualmente) face a face, então considerem criar um comentário para resumir o que conversaram.
Faça o merge somente quando você tiver confiante e o seu sistema de integração contínua mostrar que os testes e builds estão OK.

Resolvendo conflitos

Exija ao menos 2 revisores de código.

Eventualmente o autor do PR e o revisor poderão discordar. Isso é perfeitamente normal e na verdade é um sinal de uma boa dinâmica de time. Entretando, o que não é normal é ter discussões intermináveis ou um desenvolvedor passar por cima do outro por preferências pessoais, senioridade, acessos, etc.

É bom se prevenir dessas situações e ter uma estratégia para resolver conflitos. Um bom método é ter pelo menos 2 revisores. Nesses casos, é simplesmente a solução do voto da maioria que será aderida.

Traduzido e adaptado de:

Best practices for reviewing pull requests
Pull request best practices

Forem: Filipe