Un PR de 47 archivos, descripción "fix bug", abierto el viernes a la tarde. El revisor aprueba por cansancio, y el defecto llega a producción con dos firmas encima. Ese escenario aparece en todo equipo que revisa código, y casi todo en él es evitable.

Cómo escribes el pull request condiciona el tiempo de ciclo del equipo entero. Un PR bien hecho lleva al revisor directo al punto que necesita juicio, y responde la pregunta del test antes de que la haga.

Qué traba la revisión

  • Alcance grande. Un PR que toca 15 archivos en 3 contextos pasa de 20 minutos de revisión, y el revisor elige entre estudiar todo o aprobar por encima. La aprobación por encima se vuelve aprobación sin lectura. El post del Google Testing Blog In Praise of Small Pull Requests mide el efecto del tamaño del PR en la revisión y en la detección de defectos.
  • Descripción genérica. "Refactor" obliga al revisor a leer el diff entero para reconstruir tu intención.
  • Formateo mezclado con lógica. Reindentación y reordenación de imports en el mismo PR esconden la línea que cambia comportamiento.
  • Sin test nuevo. El revisor abre el diff buscando el test que prueba el cambio y no lo encuentra. Pregunta, y el ciclo se extiende un día más.

Anatomía de un PR que pasa rápido la revisión

Título con tipo

Conventional Commits resuelve: feat(auth): rota jwt-autenticacao-completa" class="post-internal-link">refresh token al hacer login informa tipo, scope y cambio sin abrir la página del PR.

Descripción en tres bloques

## Qué
Rotación automática de refresh token al hacer login.
El token anterior se invalida en el mismo request.

## Por qué
Cierra CVE-2024-XXXX: un token de larga duración sin rotación
sufre session fixation después del logout.

## Cómo revisar
- Empieza por el middleware en `auth/refresh.ts`
- La invalidación queda en `token-store.ts:47`
- El test de integración del flujo está en `auth.test.ts`

Una responsabilidad por PR

La regla que aplico: el PR tiene que caber en 20 minutos de revisión de alguien que conoce el dominio. Por encima de eso, el diff se lee incompleto, y pierdes la segunda opinión que pediste al revisor. La documentación de pull requests de GitHub describe el flujo de rama de feature y revisión que usa este patrón.

Formateo en un PR propio

¿Reformateaste el archivo? Manda el PR de formateo separado, con la herramienta explicada en la descripción. El PR de lógica queda legible, y el git blame apunta al cambio de comportamiento en lugar del formatter.

Evidencia del resultado

¿Cambiaste UI? Agrega el screenshot antes y después. ¿Cambiaste performance? Agrega el número medido. ¿Cambiaste comportamiento visible? Adjunta un GIF corto del flujo. El revisor valida el cambio sin levantar la rama en local.

Auto-revisión antes del request

Abre el diff como si fuera de otra persona. Busca console.log de debug, un TODO que quedó atrás, comentarios muertos, imports sin uso. Dos minutos acá ahorran el ciclo de ida y vuelta que estira un PR durante días.

Checklist antes de pedir revisión

  • Título con tipo de Conventional Commits.
  • Descripción con qué, por qué y por dónde empezar a leer.
  • Una responsabilidad por PR.
  • Formateo fuera del cambio de lógica.
  • Test para el caso agregado o modificado.
  • Screenshot, número o GIF para el cambio visible.
  • Sin console.log, debugger o TODO olvidados.
  • El diff leído una vez por ti, con ojos de revisor.

Cada item que falta se vuelve una pregunta en la revisión, y una pregunta se vuelve otro ciclo. El recurso de rama protegida de GitHub cubre el requisito de aprobación antes del merge. El resto del checklist depende de quien abre el PR.