PRs en Pila (Stacked PRs)

¿Qué hace PRs en Pila (Stacked PRs)?

El presupuesto de tamaño

Apunte a aproximadamente 300 líneas modificadas por PR, con 500 como límite máximo. A ese tamaño un humano puede mantener todo el cambio en su cabeza para una revisión rápida, y los agentes de revisión devuelven hallazgos limpios y específicos en lugar de pasar por encima.

Lo que cuenta: código escrito a mano y pruebas.

Lo que no cuenta: archivos de bloqueo (lockfiles), código generado (migraciones, codegen, salida de OpenAPI), snapshots, fixtures y archivos vendidos. Se revisan por encima, no se leen. Enumere qué archivos son generados en el cuerpo del PR para que el revisor sepa qué saltar.

Divida antes de escribir, no después. La división se decide en el plan (ver coding-process). Si una etapa planificada superaría 500, vuelva a planificarla. Puntos de división comunes:

• Las pruebas pueden ser su propia etapa. Por ejemplo, lógica con pruebas unitarias y de integración, luego interfaz de usuario con pruebas E2E.
• Esquema o modelo de datos, luego el servicio que lo usa, luego la superficie de la API, luego la interfaz de usuario.
• Una refactorización que haga fácil el cambio, luego el cambio.
• Una sincronización de documentación que sea demasiado grande para acompañar obtiene una etapa solo de documentación encima.

Cambios genuinamente indivisibles, como una migración cohesiva o un renombrado en 80 archivos, pueden excederse. El cuerpo del PR dice por qué y señala al revisor la parte que realmente necesita lectura.

Los commits atómicos siguen aplicándose dentro de cada PR. El presupuesto es por PR y no reemplaza la higiene de commits.

Apilamiento (Stacking)

El trabajo de varias etapas se entrega como una pila de PRs, nunca como una sola rama que lleva todo el plan. Cada PR es una etapa y apunta a la rama de la etapa anterior, no a main. Así, cada diff que ve el revisor es solo el cambio de esa etapa, y una etapa riesgosa (una migración, un cambio de autenticación) puede revisarse y revertirse por sí sola.

• Rama cada etapa a partir del último commit de la etapa anterior. Solo el PR inferior apunta a main:

  gh pr create --base <rama-etapa-anterior>
  

• Anote la posición en el cuerpo de cada PR (Apilado sobre #123) para que un revisor que abra uno fuera de orden sepa lo que está viendo.
• Integre de abajo arriba. Cuando una rama base cambia (una corrección de revisión o la fusión de la base), haga rebase de las ramas superiores y haga force-push de esas. Hacer force-push de sus propias ramas de pila sin fusionar es rutinario. Hacer force-push de main o de una rama compartida nunca lo es.
• Después de que cualquier PR en la pila se fusione, sincronice el resto sobre la nueva base antes de comenzar la siguiente etapa.
• Las correcciones de una revisión o verificación en una superficie de interfaz de usuario se entregan como una nueva etapa encima, para que la compilación y las correcciones se mantengan revisables por separado.
• Herramientas de apilamiento como gh stack, Graphite o git-town son opcionales. Git simple y gh son suficientes.

Revisión secuencial

Revise una pila una etapa a la vez. Solicite revisión al revisor del proyecto (ver puertas del proyecto en AGENTS.md) solo en el PR inferior, luego:

1. Solicite revisión en esa única etapa.
2. Aborde cada hallazgo (ver más abajo).
3. Vuelva a solicitar revisión y repita hasta que la etapa esté aprobada.
4. Solo entonces solicite revisión en la siguiente etapa.

No solicite revisión de toda la pila a la vez. Un hallazgo en la etapa 1 puede invalidar comentarios ya escritos en las etapas 2 a 5, y la revisión secuencial mantiene acotado el esfuerzo del revisor.

Si una etapa se estanca (no llega revisión o hay un hallazgo que necesita una decisión de producto), márquelo y siga construyendo las etapas superiores localmente donde no dependan de la respuesta.

Manejo de hallazgos de revisión (cualquier PR, apilado o no)

• Verifique técnicamente cada hallazgo antes de actuar. Lea el código al que apunta y reproduzca el problema si puede.
• Corríjalo, o rechácelo con fundamentos. Los revisores, humanos o bots, se equivocan con confianza como un evento normal. Hacer un cambio malo para parecer complaciente es peor que discutir. Sin acuerdo fingido.
• Juzgue los hallazgos por probabilidad real. Rechace correcciones para escenarios que no pueden ocurrir realmente y sugerencias que añaden complejidad sin beneficio real.
• No añada pruebas que no puedan fallar. Una prueba que pasa independientemente de si el error existe es ruido. Ejecútela primero contra el código roto (ver testing).
• Responda a cada hallazgo para que el revisor pueda ver qué pasó: corregido en qué commit, o por qué no.