Pull Request Checklist: 12 itens antes do review

Antes de abrir um pull request, pare e revise seu próprio código com uma checklist. Ela não é burocracia, é o que separa um PR que o revisor aprova rápido de um que gera dez comentários de ajuste. Use esta lista sempre que for submeter uma mudança, seja em um projeto pessoal ou em time grande.

Descrição do PR

1. Título claro e objetivo

O título deve dizer o que a mudança faz, não como. "Corrige erro de login com email duplicado" é melhor que "fix bug". Quem lê o histórico depois precisa entender sem abrir o diff.

2. Contexto e motivação

Explique por que a mudança existe. Uma linha sobre o problema original ajuda o revisor a avaliar se a solução ataca a causa certa.

3. Testes descritos

Liste o que você testou manualmente e quais testes automatizados rodou. Se não testou, diga. Revisor que sabe o que foi coberto confia mais no resultado.

Código

4. Mudança mínima necessária

O PR deve conter apenas o necessário para resolver a tarefa. Refatoração não relacionada atrasa o review e aumenta o risco de conflito.

5. Sem código comentado ou debug

Remova console.log, prints temporários e blocos comentados. Eles poluem o diff e confundem quem lê depois.

6. Nomes que explicam intenção

Variáveis e funções com nomes descritivos reduzem a necessidade de comentários. Se você precisa de um comentário para explicar o que o código faz, considere renomear.

7. Tratamento de erros

Pergunte-se: o que acontece se a API falhar, se o arquivo não existir, se o usuário mandar dado inválido? Seu código deve responder a isso de forma previsível.

Testes

8. Cobertura do caso principal

Existe teste para o fluxo feliz? Sem isso, o revisor não tem como saber se a mudança quebra algo no caminho comum.

9. Cobertura de casos de borda

Teste também o que pode dar errado: entrada vazia, valor limite, permissão negada. É onde a maioria dos bugs aparece.

10. Rodou a suíte completa

Não rode só o teste do seu módulo. A mudança pode quebrar outra parte do sistema que depende do mesmo código.

Antes do merge

11. Conflitos resolvidos

Atualize sua branch com a main antes de pedir review. PR com conflito obriga o revisor a adivinhar o que vai ficar.

12. Releitura do diff

Abra o diff completo e leia como se fosse outra pessoa. Você vai pegar erros que passaram na hora de escrever.

O erro mais comum que vejo é pular a releitura final do diff. O autor confia na memória do que escreveu e não percebe uma variável não usada ou um if invertido. A leitura fria do diff, item 12, é a que mais economiza tempo de review.

Perguntas frequentes

O que é um pull request checklist?

É uma lista de critérios verificáveis que o autor confere antes de submeter o código para revisão. Ela cobre descrição, código, testes e integração, e serve para padronizar a qualidade mínima do que vai para review.

Como criar um pull request checklist no GitHub?

Crie um arquivo de template na pasta .github do repositório. O GitHub usa esse arquivo automaticamente ao abrir um novo PR, preenchendo a descrição com os itens que você definir.

Pull request checklist é obrigatório?

Não é obrigatório, mas time que usa checklist reduz retrabalho. Sem ela, o revisor gasta tempo apontando erros básicos que o autor poderia ter pego sozinho.

Qual a diferença entre pull request e code review?

O pull request é o mecanismo de propor a mudança. O code review é o processo de avaliação dessa mudança por outra pessoa. A checklist fica entre os dois, preparando o código para o review.

Posso usar a mesma checklist para PRs pequenos?

Para correções de uma linha, itens como descrição detalhada podem ser resumidos. Mas a releitura do diff e o teste do caso principal continuam valendo, mesmo no PR menor.