PR de 47 arquivos, descrição "fix bug", aberto na sexta tarde. O revisor aprova por exaustão, e o defeito segue para produção com assinatura de duas pessoas. Esse cenário aparece em todo time que revisa código, e quase tudo nele é evitável.

A forma como você escreve o pull request influencia o tempo de ciclo do time inteiro. PR bem feito leva o revisor direto ao ponto que precisa de julgamento e responde a pergunta de teste antes dela aparecer.

O que trava a revisão

  • Escopo grande. PR que toca 15 arquivos em 3 contextos passa de 20 minutos de revisão, e o revisor decide entre estudar tudo ou aprovar por cima. Aprovação por cima vira aprovação sem leitura. O In Praise of Small Pull Requests do Google Testing Blog mede o efeito do tamanho de PR na revisão e na detecção de defeito.
  • Descrição genérica. "Refactor" obriga o revisor a ler o diff inteiro para reconstruir a sua intenção.
  • Reformatação misturada com lógica. Indentação e reordenação de imports no mesmo PR escondem a linha que muda comportamento.
  • Sem teste novo. O revisor abre o diff procurando o teste que prova a mudança e não acha. Ele pergunta, e o ciclo estende mais um dia.

Anatomia do PR que passa rápido na revisão

Título com tipo

Conventional Commits resolve: feat(auth): gira jwt-autenticacao-completa" class="post-internal-link">refresh token no login informa tipo, escopo e mudança sem abrir a página do PR.

Descrição em três blocos

## O quê
Rotação automática de refresh token no login.
O token anterior é invalidado na mesma requisição.

## Por quê
Fecha CVE-2024-XXXX: token de longa duração sem rotação
sofre session fixation depois do logout.

## Como revisar
- Comece pelo middleware em `auth/refresh.ts`
- A invalidação fica em `token-store.ts:47`
- O teste de integração do fluxo está em `auth.test.ts`

Uma responsabilidade por PR

A regra que eu aplico: o PR precisa caber em 20 minutos de revisão por quem conhece o domínio. Acima disso, o diff fica incompleto na leitura, e você perde a segunda opinião que contratou o revisor para ter. A documentação de pull requests do GitHub descreve o fluxo de branch de recurso e revisão que esse padrão usa.

Reformatação em PR próprio

Reformatou o arquivo, manda o PR de formatação separado com a ferramenta explicada na descrição. O PR de lógica fica legível, e o git blame aponta a mudança de comportamento em vez do formatter.

Evidência do resultado

Mudou UI, coloque o screenshot antes e depois. Mudou performance, coloque o número medido. Mudou comportamento visível, anexe um GIF curto do fluxo. O revisor valida a mudança sem subir a branch local.

Auto-revisão antes do request

Abra o diff como se fosse de outra pessoa. Procure console.log de debug, TODO que ficou para trás, comentário morto, import sem uso. Dois minutos aqui poupam o ciclo de ida e volta que estende o PR por dias.

Checklist antes de pedir revisão

  • Título com tipo do Conventional Commits.
  • Descrição com o quê, por quê e onde começar a ler.
  • Uma responsabilidade por PR.
  • Reformatação fora da mudança de lógica.
  • Teste para o caso novo ou alterado.
  • Screenshot, número ou GIF para mudança visível.
  • Sem console.log, debugger ou TODO esquecido.
  • Diff lido uma vez por você, com olho de revisor.

Cada item que falta vira pergunta no review, e pergunta vira ciclo de revisão. O recurso de branch protegida do GitHub cobre o requisito de aprovação antes do merge. O resto do checklist depende de quem abre o PR.