Acerca de las pull requests apiladas

Acerca de las pull requests

Las solicitudes de incorporación de cambios apiladas son dos o más solicitudes de incorporación de cambios en el mismo repositorio, donde:

• La primera solicitud de extracción, o la inferior, tiene como destino el tronco de la pila, normalmente la rama predeterminada del repositorio, como main, aunque puede ser cualquier rama, como una rama de versión.
• Cada solicitud de incorporación de cambios subsiguiente tiene como destino la rama de la solicitud de incorporación de cambios debajo de ella.

   ┌── feat/frontend     → PR #3 (base: feat/api-endpoints)  ← top
  ┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer     → PR #1 (base: main)               ← bottom
main (default base branch)

Las ramas apiladas forman una cadena de dependencias, donde cada rama se basa en la que se encuentra debajo. Los cambios fundamentales, como los tipos compartidos y el esquema de base de datos, van en ramas inferiores y el código que depende de ellos, como las rutas de API y los componentes de la interfaz de usuario, van en ramas superiores.

Cada pull request de una pila representa un cambio discreto y revisable de uno o más commits. Puede revisar e iterar sobre cada solicitud de incorporación de cambios de forma independiente, y cada una muestra solo la diferencia para su capa y los cambios entre su rama y la rama debajo de ella.

El principio clave: si el código de una capa depende del código de otra capa, la dependencia debe estar en la misma rama o en una inferior. Cree una rama al iniciar una línea de trabajo diferente que dependa de lo que haya creado hasta ahora. Por ejemplo, al cambiar de back-end a trabajo de front-end, pasar de la lógica principal a las pruebas o cuando la rama actual ya es lo suficientemente grande como para revisarla.

¿Por qué usar GitHub pull requests apiladas?

Finaliza un cambio y pasa directamente al siguiente

Las solicitudes de incorporación de cambios encadenadas le permiten abrir una nueva solicitud de incorporación de cambios sobre una que todavía está abierta. Durante un proyecto grande, el siguiente cambio puede depender del trabajo que aún no se haya integrado. En lugar de esperar a que se combine, con una pila, puede seguir desarrollando.

Con cada pull request en una pila que contiene un cambio específico, los revisores ven un pequeño diff para cada capa en lugar del pull request grande. Las solicitudes de incorporación de cambios más pequeñas son más rápidas de revisar, menos propensas a ser revisadas por encima y es menos probable que se vuelvan obsoletas y desarrollen conflictos de combinación.

Adecuado para el desarrollo de gran volumen

Cuando se genera una gran cantidad de código a la vez, a menudo con agentes de inteligencia artificial, un stack da a cada cambio un lugar al que ir. Un agente completa una tarea y, a continuación, inicia la siguiente tarea que se basa en ella. Esa secuencia se asigna directamente a una pila: una solicitud de incorporación de cambios por tarea, cada una basada en la de abajo. Stacks permiten registrar esas dependencias explícitamente en lugar de combinar cambios no relacionados en una sola rama.

Ventajas del uso de pull requests apiladas en GitHub

Sin usar pull requests apiladas, dividir un gran cambio en pull requests más pequeñas y dependientes crea trabajo adicional:

• Administración de sucursales. Hacer rebase y mantener las ramas sincronizadas entre las solicitudes de incorporación de cambios dependientes es tedioso y propenso a errores.
• Reglas y CI. Las reglas de protección de rama y las comprobaciones de CI a menudo solo se desencadenan para la pull request inferior en la cadena, lo que dificulta conocer el verdadero estado del resto.
• Revisar el contexto. Revisar un único cambio fuera del contexto del resto del conjunto de cambios puede reducir la calidad de la revisión.

Las pull requests apiladas abordan estos problemas al tratar la cadena de pull requests como una unidad conectada mientras se mantiene cada capa pequeña y centrada.

Rebasing

La rebasificación es la parte más complicada de trabajar con pilas y GitHub la gestiona automáticamente. Puede desencadenar un rebase en cascada del lado del servidor desde la pull request o ejecutar un rebase local en cascada con la extensión gh stack en GitHub CLI. Al combinar una pull request en la parte inferior de la pila, las ramas restantes se reajustan mediante rebase automáticamente para que la siguiente pull request tenga como destino la rama base predeterminada.

¿Dónde puede usar solicitudes de extracción en pila?

Las pull requests apiladas están disponibles en los siguientes casos:

• GitHub CLI
• Sitio web de GitHub
• GitHub Mobile
• Soporte programático a través de webhooks, API REST y GraphQL
• Para los agentes, a través de la gh-stack habilidad

En GitHub CLI

La gh stack extensión de GitHub CLI gestiona el flujo de trabajo de desarrollo local. Puede crear y realizar un seguimiento de las ramas en el orden de dependencia correcto, mantener las ramas actualizadas mediante rebase, hacer push de las ramas, crear y vincular solicitudes de incorporación de cambios y navegar entre capas. Consulte Comandos de la CLI para pull requests apiladas.

En el GitHub sitio web

Cuando una pull request forme parte de un stack, verá lo siguiente:

• Icono de pila en la parte superior de la pull request con un número que indica qué capa está viendo.
• Aparece un mapa de pila en el cuadro de combinación. Muestra cada pull request de la pila y su estado, y le permite navegar a cualquier nivel con un solo clic. El tronco (rama base predeterminada) está en la parte inferior, con cada pull request de la pila destinada a la rama de la pull request que tiene debajo.

Compatibilidad mediante programación a través de webhooks, API REST y GraphQL

Las solicitudes de incorporación de cambios apiladas están disponibles mediante programación, por lo que puede integrarlas en sus propias herramientas, automatización y paneles:

• Los webhooks incluyen un stack objeto en pull_request payloads de evento, por lo que la automatización puede responder cuando un pull request se añade a una pila, se mueve dentro de una pila o sale de una pila.
• La API REST lee la pertenencia a la pila de una pull request y proporciona endpoints para enumerar, crear, ampliar y disolver pilas.
• La API de GraphQL expone campos de solo stack lectura en una solicitud de extracción para consultar la pila y la posición de la solicitud de extracción en ella.

Reglas, CI y fusión

Reglas y aplicación de CI

Las pull requests apiladas admiten flujos de trabajo GitHub Actions.

Los requisitos de combinación para cualquier solicitud de extracción de la pila se determinan mediante la rama base de la solicitud de extracción inferior, normalmente main.

• Las reglas de protección de rama, como las aprobaciones de CODEOWNER, se aplican en todas las pull requests de la pila, incluso en las pull requests intermedias de la pila que no tienen como destino directamente la rama predeterminada.
• Las comprobaciones de CI desencadenadas por los pull requests en tu rama predeterminada se ejecutan para todos los pull requests de la pila, no solo para el inferior.

Esto garantiza que cada capa de la pila cumpla el mismo estándar de calidad antes de poder fusionarse.

Combinación

Puede combinar toda la pila, una única solicitud de incorporación de cambios o una parte de la pila que abarca varias solicitudes de incorporación de cambios. No es necesario fusionar toda la pila de una vez, pero las pull requests deben fusionarse de abajo hacia arriba.

• Fusiona toda la pila a la vez fusionando la pull request superior. Cada solicitud de extracción que aparece debajo la incluye.
• Fusiona parte de la pila fusionando una pull request intermedia. Las solicitudes de incorporación de cambios siguientes también se combinan y las solicitudes de incorporación de cambios anteriores permanecen abiertas y cambian automáticamente su rama de destino a la rama base de la pila.

Las pilas admiten métodos de commit de fusión, squash y fusión mediante rebase, y son compatibles con la cola de fusión. El historial de confirmaciones resultante es el mismo que el de fusionar individualmente cada solicitud de incorporación de cambios, empezando por la parte inferior.

Pasos siguientes

• Inicio rápido para pull requests apiladas
• Implementación de solicitudes de incorporación de cambios apiladas en su organización