Motivação

Tudo começou quando percebi um padrão preocupante no meu trabalho atual: os desenvolvedores demoravam muito mais tempo para revisar PRs grandes. Curioso com essa situação, decidi fazer uma pesquisa(interna) com a equipe para entender melhor o problema. A resposta foi unânime: quando um PR era grande, os desenvolvedores precisavam de um período significativo de tempo para fazer uma revisão adequada, o que significava interromper o trabalho que estavam fazendo. Isso criava um bloqueio muito grande para o autor do PR.

Por outro lado, quando os PRs eram pequenos, a história era completamente diferente. Os desenvolvedores paravam o que estavam fazendo para fazer a revisão rapidamente, mantendo o fluxo de trabalho ágil e eficiente.

Com os resultados em mão, decidimos estabelecer um limite prático: máximo de 15 arquivos alterados por PR. Para monitorar e melhorar essa prática, implementamos uma GitHub Action que adicionava automaticamente um label “too large” em PRs que excediam esse limite. No início, o número de PRs com esse label era alarmante, mas isso nos deu uma métrica clara para acompanhar nossa evolução.

Com o tempo(e muita insistência da minha parte) a equipe começou a se adaptar à nova cultura de PRs pequenos. Hoje, é raro ver um PR com o label “too large”, e o processo de revisão flui muito mais suavemente. Esta experiência me mostrou na prática o valor de manter PRs pequenos e focados.

Quais os reais benefícios percebidos?

1. Revisões Mais Rápidas e Eficientes

PRs menores são mais fáceis de revisar. Enquanto um PR grande pode exigir um período de tempo significativo para revisão, PRs pequenos podem ser revisados em intervalos curtos, tornando o processo mais ágil e menos oneroso para os revisores.

2. Maior Qualidade nas Revisões

Com menos código para analisar, os revisores podem se concentrar melhor em potenciais problemas com mais precisão. Em PRs grandes, é comum que pontos importantes passem despercebidos devido à sobrecarga de informações.

3. Menor Probabilidade de Bugs

Mudanças menores são mais fáceis de testar e validar. Tanto o autor quanto o revisor conseguem entender melhor o impacto das alterações, reduzindo a chance de introduzir bugs.

4. Código modular

A necessidade de escrever código em pequenos pedaços naturalmente leva a um design mais modular e desacoplado, pois você é forçado a pensar em como dividir a funcionalidade em partes menores e mais coesas.

Como escrever PRs pequenos

  1. Sempre pense em pré-mudanças, mudanças e pós-mudanças. Em outras palavras, não escreva uma feature completa em UM ÚNICO PR.

  2. Novos arquivos devem ser adicionados separadamente com antecedência se estiverem misturados com outras mudanças.

  3. Separe as refatorações em PRs diferentes.

  4. Escreva código desacoplado que possa ser “deployado” a qualquer momento.

Muita gente trabalha com sistema de tickets(como JIRA) e normalmente as pessoas criam um PR para um ticket, o que pode ser um problema se o ticket for para uma feature grande. O ideal é que você crie vários PRs para um ticket.

Quando PRs grandes são aceitáveis?

Existem algumas situações onde PRs maiores podem ser justificáveis:

  • Remoção de arquivos inteiros
  • Mudanças que são intrinsecamente grandes e não podem ser divididas

Conclusão

Manter PRs pequenos não é apenas uma boa prática, é uma estratégia que beneficia toda a equipe. Aumenta a qualidade do código, acelera o processo de revisão e reduz a probabilidade de erros. Embora possa parecer mais trabalhoso no início, os benefícios a longo prazo superam amplamente qualquer esforço adicional.

P.S

Na época em que estávamos fazendo essa mudança lá na empresa, o blog The Pragmatic Engineer escreveu um artigo sobre como usar stacked diffs, que é uma técnica muito boa para escrever PRs pequenos.