Revisão de Pull Requests
Justificativa
Alguns repositórios da organização têm proteção de branches, que impede alterações diretas nas branches principais (main, master, entre outras). Essa proteção é sólida contra commits acidentais, mas não impede que um desenvolvedor mescle uma Pull Request sem a aprovação de outra pessoa, o que facilita burlar a regra.
É necessário, portanto, um processo de revisão que garanta qualidade e conformidade, mas mantenha o fluxo de entregas acelerado e evite que PRs fiquem "engasgadas", travando a equipe.
As práticas desta página foram retiradas da documentação open-source da Google e estão resumidas aqui. Recomenda-se a leitura da documentação original.
Fluxo de revisão
Princípios da revisão
- O objetivo é garantir que a saúde e a qualidade do código sejam mantidas e evoluam.
- Não existe código perfeito. Revisores não devem exigir perfeição para aprovar.
- A revisão também capacita o time: deixe comentários que ajudem a pessoa a aprender algo novo (framework, linguagem, padrões de projeto, arquitetura etc.).
- Diretrizes de nomenclatura (variáveis, funções e outros tipos) são inegociáveis. Se não houver padrão pré-estabelecido, o padrão usado pelo autor deve ser aprovado.
O que buscar em uma Pull Request
| Aspecto | O que verificar |
|---|---|
| Design | A lista de alterações faz sentido para o objetivo, interage corretamente com o resto do sistema e corresponde a um objetivo da sprint. |
| Funcionalidade | Pense como usuário e como desenvolvedor: as alterações atendem às necessidades do usuário e facilitam o trabalho de outros devs? Procure problemas técnicos e de UI, faça testes exploratórios e avalie riscos como concorrência de memória e deadlocks. |
| Complexidade | As alterações estão mais complexas do que deveriam? Siga KISS e YAGNI. |
| Testes | Os testes existem e são adequados à alteração (conforme a regra da liderança). |
| Comentários | Estão na língua do projeto? São realmente necessários? |
| Documentação | Se a interação de usuários ou desenvolvedores com o sistema mudou, toda a documentação deve ser atualizada. |
Checklist do revisor
Checklist resumido a ser verificado em uma PR:
## Itens de Revisão
- [ ] O implementado corresponde à tarefa.
- [ ] O código está bem estruturado.
- [ ] O código segue os princípios KISS e YAGNI.
- [ ] Os padrões de nomenclatura e estilização de código estão corretos.
- [ ] Os comentários são claros, necessários e atualizados.
- [ ] Os testes unitários estão implementados corretamente.
- [ ] O implementado funciona corretamente.
- [ ] As mudanças visuais funcionam corretamente.
- [ ] A documentação está atualizada.