Dicas para uma descrição de PR melhor

Wagner Cardoso — Fri, 29 Apr 2022 00:06:03 +0000

Fala meu povo! Virei dev blogueiro e espero agregar conhecimento e ajudar vocês de alguma forma. Neste primeiro post decidi falar sobre uma parte essencial do desenvolvimento e que nem sempre é dada a devida atenção: pull requests. Irei falar um pouco sobre minhas percepções e dar algumas dicas que acho relevantes para facilitar a revisão dos seus colegas de time.

O que é uma Pull Request ?

Segundo a documentação do GitHub:

As pull requests permitem que você informe outras pessoas sobre as alterações das quais você fez push para um branch em um repositório.

Basicamente nós usamos os queridos PR's para adicionarmos uma nova feature ou correção ao código do sistema que estamos trabalhando.

Nossos colegas analisam as alterações que queremos adicionar e podem aprovar ou não de acordo com seu julgamento. Muitas vezes nossos colegas não tiveram contato com a tarefa durante o desenvolvimento dela e chegam para revisar nosso código sem ter o background necessário para apenas dar o approve e seguir a vida.

Para isso, podemos deixar o texto do nosso PR rico o suficiente para a pessoa que estiver revisando tenha um entendimento melhor da tarefa. A seguir, vou dar algumas dicas de como facilitar o entendimento do seu trabalho em um PR.

O que fazer para melhorar o texto do seu PR

Nunca deixe a descrição vazia

Nada pior do que abrir o PR que você precisa revisar e ele estar sem descrição alguma. Ler o código de alguém nem sempre é uma tarefa fácil, e não termos nenhum contexto sobre o problema dificulta ainda mais. Então, nunca se esqueça: PR sem descrição JAMAIS!

Explique o contexto

Essa talvez seja a parte mais importante do PR. Aqui você vai explicar o motivo da tarefa existir, quais as características do problema e como você chegou na resolução. Quem estiver revisando deve sair deste tópico com um entendimento geral do problema, o que irá facilitar muito no momento de revisar o código. Com esse contexto geral do problema, o reviewer poderá pensar em possibilidades de melhoria e conseguir enxergar melhor problemas no seu código.

Resuma seu desenvolvimento

Aqui iremos dar uma passada nas alterações feitas, resumindo em palavras o código que escrevemos. Isso dá ao reviewer uma ideia geral do seu pensamento para resolver a tarefa e já possibilita a identificação de problemas com a sua abordagem.

Diga qual é o objetivo do desenvolvimento

Nem sempre o objetivo principal fica claro apenas com o contexto da tarefa e o resumo do desenvolvimento. Deixe bem explícito o objetivo do PR, que servirá como norte ao reviewer irá testar a feature/correção logo depois.

Dê instruções de como testar

Às vezes trabalhamos em sistemas complexos, onde simplesmente subir uma versão local é uma tarefa árdua. Em outros casos, nossa tarefa pode se comunicar com vários projetos diferentes, o que dificulta ainda mais o processo de testagem do PR. Para contornar o problema, dê instruções claras de como deixar o ambiente pronto para rodar os testes necessários. Qualquer informação relevante para o teste em si deve ser informado aqui.

Deixe observações

Às vezes nosso PR possui um detalhe tão específico que vale a pena o reviewer saber. Aqui nós colocamos avisos, alguma ação necessária, etc.

Coloque os links necessários

Algo que pode ajudar e muito o reviewer é compilar os links necessários para ele não precisar perder tempo procurando os locais que são dependência para o teste.

Exemplo de descrição de um PR

Pense na seguinte situação: é preciso alterar o payload que chega numa fila do SQS para que a lambda que consome a fila seja executada corretamente.

Tendo este cenário em vista, um exemplo de descrição de PR com as dicas dadas anteriormente é:

Exemplo

Contexto: após o desenvolvimento do endpoint que processa os agendamentos da clínica, foi constatado que o endpoint está enviando o payload incompleto, faltando a informação de endereço do paciente.

Desenvolvimento: a informação de endereço foi adicionada ao payload da fila que é enviado no controller de agendamento.

Objetivo: o payload deve chegar correto na fila e a lambda processar corretamente o agendamento.

Como testar:

publicar o ambiente de homologação do servidor com a branch do PR;
chamar o endpoint de agendamentos (/schedules);
verificar se o payload chegou corretamente na fila;
verificar se a lambda processou corretamente o agendamento;

Observações: caso dê algum erro ao publicar, basta publicar a branch main e depois a branch da issue. Temos uma trava que impossibilita a publicação de branches que não a main para a partir de branches diferentes da main. Isso evita possíveis problemas com o ambiente.

Links úteis:

documentação de publicação no ambiente de homologação (informa link);
fila SQS para verificação do payload (informa link);
lambda que processa as mensagens da fila SQS (informa link);

Considerações finais

Normalmente escrevemos código para outras pessoas lerem e usarem. Nos preocupamos com o entendimento delas em relação ao que desenvolvemos. Este mesmo pensamento deve ser colocado em prática ao criarmos um PR. Devemos nos preocupar com o reviewer do nosso PR, pois quanto mais informações e auxílios darmos, melhor será sua revisão e consequentemente melhor nosso código irá ficar, mais iremos aprender e mais valor será agregado à empresa.

Cada time de desenvolvimento possui suas características, regras e conjunto de boas práticas, porém essas dicas podem ajudar muito no seu dia-a-dia de trabalho.

É isso meu povo. Este foi meu primeiro post e fico muito feliz de você ter lido até o final. Paz e sucesso pra ti!

DEV Community: Wagner Cardoso