Existe una forma de medir la madurez técnica de un ingeniero que va más allá del código que escribe: cómo escribe pull requests. Un PR bien hecho no es solo código: es comunicación, documentación y respeto por el tiempo de las personas que van a revisarlo.

Los PRs malos llegan el viernes por la tarde con 47 archivos modificados, una descripción de tres palabras ("fix bug") y ningún contexto sobre qué cambió, por qué cambió y a qué debe prestar atención el revisor. La mayoría de las personas en esa situación aprueba el PR por cansancio, y eso es un riesgo técnico real.

Qué hace un PR difícil de revisar

Antes de hablar de lo que funciona, vale entender lo que no funciona:

  • Alcance demasiado grande. Un PR que toca 15 archivos en 3 contextos distintos es casi imposible de revisar con profundidad. Los revisores no tienen contexto suficiente para evaluar todo, y terminan aprobando superficialmente.
  • Descripción ausente o genérica. "Refactor" o "Update logic" no dicen nada. El revisor tiene que leer todo el diff para entender qué se hizo.
  • Cambios de estilo mezclados con cambios de lógica. Reformateos y reindentaciones en el mismo PR que cambia lógica de negocio dificultan encontrar lo que importa revisar.
  • Sin contexto de test. "¿Cómo valido que esto funciona?" es la pregunta que todo revisor tiene, y que un buen PR responde antes de que sea hecha.

La anatomía de un PR bien hecho

Título descriptivo con tipo

Sigue Conventional Commits en el título: feat(auth): add JWT refresh token rotation es mucho mejor que "Update auth". El tipo, el scope y qué cambia deben estar visibles sin abrir el PR.

Descripción estructurada

Una descripción de PR eficiente responde tres preguntas: ¿Qué se hizo? ¿Por qué fue necesario? ¿Cómo debe abordarlo el revisor?

## Qué
Agrega rotación automática de refresh tokens al hacer login.
Los tokens anteriores son invalidados en la misma request.

## Por qué
Resuelve CVE-2024-XXXX: tokens de larga duración sin rotación
son vulnerables a ataques de session fixation después de logout.

## Cómo revisar
- Empieza por el middleware en `auth/refresh.ts`
- La lógica de invalidación queda en `token-store.ts:47`
- Los tests de integración cubren el flujo completo en `auth.test.ts`

Scope enfocado

La regla práctica: un PR debe ser revisable en menos de 20 minutos por alguien con contexto del dominio. Si va a pasar de eso, divídelo en PRs más pequeños. No es burocracia, es respeto por el proceso de revisión.

Separa el reformateo de la lógica

Si vas a reformatear un archivo, hazlo en un PR separado. Así el revisor del PR de lógica puede enfocarse en lo que importa, y el historial de git queda limpio.

Screenshots y evidencias

Para cambios de UI, screenshots antes/después son obligatorios. Para cambios de performance, números antes/después. Para cambios de comportamiento, un video corto o GIF del flujo.

Esto no es opcional, es parte de la responsabilidad de quien abre el PR probar que el cambio funciona como se esperaba.

Auto-revisión antes de abrir

Una práctica que transforma la calidad de los PRs: revisa tu propio PR antes de marcar a alguien como revisor. Abre el diff como si fueras otra persona. ¿Entenderías qué se hizo? ¿Hay algún debug statement olvidado? Algún comentario TODO que debería haber sido resuelto?

Dos minutos de auto-revisión evitan ciclos de revisión que demoran días.

El checklist de PR que funciona

  • ¿El título sigue Conventional Commits?
  • ¿La descripción responde: qué, por qué, cómo revisar?
  • ¿El PR toca una única responsabilidad?
  • ¿Reformateos están separados de cambios de lógica?
  • ¿Los tests cubren los casos agregados/modificados?
  • ¿Screenshots/evidencias incluidas para cambios visibles?
  • ¿Sin console.log, debugger o TODO olvidados?
  • ¿Leíste tu propio diff una vez antes de abrir?

Ese checklist parece obvio escrito así. Pero aplicarlo consistentemente es lo que separa a los ingenieros que aceleran al equipo de los ingenieros que crean cuellos de botella en el proceso de revisión.