Que cada pull request en un stack tenga una sola decisión de revisión

Read in English → · 阅读中文版 →

Hola mi gente linda. Quería probar los stacked pull requests en un lugar suficientemente desordenado para saber si realmente sirven.

El repo tenía 10 draft PRs viejos. Dos eran intentos separados de dark mode. Dos se pisaban con emails de vuelos retrasados. Y npm test fallaba porque un test de Playwright vivía dentro del directorio de tests de Jest.

Ese era el historial de desarrollo de este repo. El trabajo se pausa. El contexto se mueve. Vuelves a una cola que necesita una forma antes de necesitar más código.

Cerré los drafts sin borrar sus ramas, y después reconstruí una sola solución real como tres pull requests: primero los test runners, después el comportamiento de locale, y al final la cobertura de navegador y CI.

• Separar Jest y Playwright para que CI nos dé una señal útil.
• Configurar el idioma del documento desde el locale activo.
• Agregar cobertura de navegador y correrla en CI.

GitHub renderizó el trabajo como un stack 3/3. Cada capa corrió CI y CodeQL. El resultado útil fue un orden de revisión que podía explicar: arreglar la señal, cambiar el comportamiento, comprobar el comportamiento.

Cada capa le da a quien revisa una sola pregunta: infraestructura de tests, comportamiento de locale, y después CI de navegador. GitHub muestra los tres PRs como un stack 3/3.

Esa experiencia me cambió la forma de pensar sobre el PR gigante.

Quien revisa tiene demasiado que hacer

Un pull request puede estar correcto, tener sus tests, y ser doloroso de revisar.

Empiezas con un cambio razonable. Después necesitas actualizar el schema. Después tipos compartidos. Después un endpoint de API. Después un componente de UI. Después tests. Después un refactor porque el código existente hace que el nuevo comportamiento se sienta forzado.

Unos días después tienes un PR de 800 líneas con seis clases de trabajo adentro.

Quien revisa tiene que construir la feature completa en su cabeza antes de poder decir algo útil. Necesita entender el modelo, seguir el comportamiento del backend, inspeccionar la UI, verificar los tests, y decidir si el refactor pertenece en el mismo cambio.

La guía de code review de SmartBear recomienda revisar entre 200 y 400 líneas de código a la vez. Más allá de 400 líneas, dice que la detección de defectos cae.

El número de 400 líneas no es lo más importante, pero cuando quien revisa tiene que sostener demasiadas decisiones sin relación al mismo tiempo, eso es un problema.

La rama envejece mientras eso pasa. Main sigue moviéndose. El feedback llega tarde, muchas veces en pila. Y después quien escribió tiene que separar los cambios de revisión del drift de la rama. Los pull requests grandes crean un problema de revisión antes de crear un problema de Git.

Un stack se gana sus ramas

Un stack útil tiene un orden de dependencias que puedes explicar.

Un diff grande le pide a quien revisa que tome seis decisiones. Un stack le da a cada capa una sola pregunta.

El modelo le da a la API algo real sobre lo que construir. La API le da a la UI un contrato. Quien revisa puede tomar una decisión a la vez y todavía ver hacia dónde va el trabajo.

Un rename de 600 líneas todavía puede ser un pull request coherente. Un cambio de 120 líneas que toca auth, persistencia y UI puede contener tres decisiones separadas. La cuenta de líneas te ayuda a notar problemas. La decisión te dice dónde cortar.

Uso cuatro preguntas antes de crear un stack:

• ¿La capa de abajo puede aterrizar segura por su cuenta, o detrás de una flag apropiada?
• ¿El feedback sobre la capa de abajo va a reformar el trabajo de arriba?
• ¿Quien revisa puede evaluar esta capa sin reconstruir la feature completa?
• ¿El orden de ramas coincide con la dependencia real de la implementación?

Si las respuestas son sí, las ramas extra se ganan su lugar.

Mira el stack completo, no solo cada corte. Tres capas que pasan la prueba por su cuenta pueden sumar una revisión que cuesta más que un solo PR bien formado. Si terminas en cuatro o cinco capas, mira el trabajo otra vez. O tiene esas decisiones separadas de verdad, o el ramificar se volvió el punto.

Una capa de abajo también puede quedarse trabada mientras las ramas de arriba se acumulan, concentrando riesgo y presión de coordinación en la base del stack.

Cuando el feedback cambia el cimiento, revisa la capa que va encima. Si la pregunta de revisión cambió, reformula o reconstruye esa capa.

Los cambios en una capa baja igual se propagan como trabajo de rebase y resolución de conflictos en cada rama de arriba.

Algún trabajo tiene que quedarse junto. Si quien revisa necesita la UI y la API en el mismo diff para juzgar el comportamiento, déjalos juntos. La meta es una revisión útil, no un diagrama de ramas prolijo.

Los agentes hacen los diffs gigantes más rápido

Los agentes de código hacen que los diffs del tamaño de una feature sean baratos. Tu agente es rápido. Quien revisa es una persona con un café en la mano.

He visto el pull request de 2,000 líneas hecho por agente. Puede tener buen trabajo adentro. También le pide a alguien que confíe en un modelo, una API, una UI, cobertura de tests, y un montón de pegamento generado — todo al mismo tiempo.

Dale al agente una forma de revisión antes de que empiece. Pídele que identifique el orden de dependencias, que construya el cimiento primero, y que mantenga cada capa centrada en una sola pregunta que quien revisa pueda responder.

Eso cambia la salida: pasa de una rama enorme a trabajo que el equipo realmente puede discutir.

Los stacks nativos mantienen las revisiones y los checks en su lugar

Las ramas dependientes son Git viejo. El trabajo alrededor de ellas siempre fue la parte dolorosa.

Los stacks nativos de GitHub mantienen la política conectada a toda la cadena. Cada PR se evalúa contra la base final del stack, normalmente main, así que reviews requeridos, CODEOWNERS y checks siguen aplicando a medida que el trabajo sube.

Merge el PR más alto para aterrizar el stack completo. Si solo mergeas parte, GitHub rebasa las capas que quedan.

Un efecto colateral: como cada PR corre sus checks contra la base del stack, el uso de CI se multiplica con el tamaño del stack. GitHub expone github.event.pull_request.stack.position y .size en las expresiones de workflow, así puedes correr los checks rápidos en cada capa y reservar la suite completa para el PR de arriba o el más bajo sin mergear. La API se encarga del cableado; la decisión del workflow es tuya.

Quería probar eso en el repo de demo. Las tres capas corrieron sus checks. El mapa del stack hizo la dependencia explícita. El sistema entendió la forma del trabajo en lugar de obligar a quien revisa a inferirla desde nombres de ramas y historial de commits.

Empieza donde las decisiones se separan

Empieza con dos capas. Elige una feature donde el cimiento y el comportamiento ya se sientan como conversaciones de revisión separadas. Abre el cimiento temprano. Deja que el feedback llegue antes de que el trabajo de arriba se endurezca.

El workflow corto es:

gh extension install github/gh-stack
gh stack init
gh stack add <branch>
gh stack submit

El walkthrough oficial de GitHub cubre los comandos y la configuración del agente en gh.io/stacks. Léelo cuando estés lista para construir.

En tu próxima feature, encuentra la primera decisión revisable de forma independiente y abre ese PR temprano.