Cambios de código de pila en las solicitudes de incorporación de cambios

Nota:

Esta característica está en versión preliminar pública y está sujeta a cambios.

Las solicitudes de incorporación de cambios grandes son difíciles de revisar y crear cuellos de botella, especialmente cuando se genera un gran volumen de código en poco tiempo. La calidad de la revisión también se degrada a medida que aumenta el tamaño de la solicitud de incorporación de cambios. Los revisores pueden esquiar el resultado, perder problemas o procrastinar y dejar la solicitud de incorporación de cambios hasta que crezca obsoleto y desarrolle conflictos de combinación.

Las solicitudes de incorporación de cambios apiladas mantienen los cambios de código grandes revisables.

A stack is a series of pull requests in the same repository where each pull request targets the branch of the pull request below it, forming an ordered chain that lands on a single branch, typically your main branch. Instead of one large pull request, you get a set of smaller pull requests. Since each pull request has its own focused diff, teammates can review and approve each layer independently.

En este tutorial se explica cómo usar las solicitudes de incorporación de cambios apiladas para crear una característica en capas revisables individualmente. En nuestro ejemplo, consideraremos cómo agregar la autenticación de usuario a una aplicación. Usaremos la gh stack extensión en GitHub CLI.

Prerequisites

Para seguir este tutorial, deberá instalar GitHub CLI y la gh stack extensión. Se necesita lo siguiente:

GitHub CLI (gh) 2.90.0 o posterior, y Git 2.20 o posterior.
- Autentíquese GitHub CLI con gh auth login.
Un GitHub repositorio en el que puede insertar.

En GitHub CLI, instale la gh stack extensión.

gh extension install github/gh-stack

1. Diseñar una pila antes de generar código

Una buena pila es como construir una casa: empezar con una base fuerte, enmarcar las paredes, instalar cableado y luego terminar el drywall. Cada capa se basa en la siguiente. Al final, un revisor debe poder leer las solicitudes de incorporación de cambios de abajo a arriba y seguir el desarrollo de la característica.

Divida la característica en capas. Cada capa debe ser un único cambio coherente que se pueda revisar por sí mismo.
- Mantenga cada capa lo suficientemente pequeña como para que su solicitud de incorporación de cambios sea una lectura rápida. Si una capa se siente como si necesita una descripción larga para revisarla, probablemente es demasiado grande.
- Decida los límites usted mismo. Posee la forma de la pila.
Ordene las capas por dependencia. Los cambios fundamentales van en la parte inferior. Todo lo que depende de ellos va más alto. Para la autenticación, puede ser:
- Capa 1: modelo de datos y migración
- Nivel 2: puntos de conexión CRUD
- Capa 3: middleware y guardias JWT
- Nivel 4: integración y pruebas unitarias

2. Cree primero la capa inferior.

Inicie la pila con la base. Todo lo anterior depende de que esta capa sea correcta.

Cree la pila y compile la primera capa en función del plan. Créelo con gh stack init BRANCH-NAME-1, considere la posibilidad de usar un prefijo para mantener ordenados los nombres de rama.
Revise el cambio antes de continuar. Un error en la capa inferior se propaga a cada rama por encima de ella, así que asígnele una revisión antes de continuar.

3. Apilar cada nueva capa de código en la parte superior

Con la base en su lugar, cree el resto de la característica una capa a la vez.

Agregue la capa siguiente e implemplemente en el contexto de las capas siguientes. Agregue una rama a la parte superior de la pila con gh stack add BRANCH-NAME-NEXT y confirme el trabajo allí.
Si una capa comienza a crecer demasiado grande, considere si se ha desfasado fuera de su plan o si realmente necesita dos capas en lugar de una.
Cree nuevas ramas para cada capa a medida que vaya, por lo que cada rama permanece una diferencia limpia e independiente.
Cuando esté listo para crear solicitudes de incorporación de cambios, envíe la pila con gh stack submit.
Deje que cada solicitud de incorporación de cambios se ponga por su cuenta. Un título centrado y una descripción concisa y significativa de la capa suele ser suficiente.

4. Revise las solicitudes de incorporación de cambios antes de solicitar una revisión.

Cada capa es pequeña, lo que facilita la auto-revisión también. Haga un pase en cada rama antes de implicar a los compañeros de equipo. Los revisores deben recibir los cambios que ya confía.

Ejecute las pruebas, los linters y el análisis de código en cada rama para comprobar cada capa con respecto a los estándares antes de solicitar revisiones.

5. Solicitar revisiones para la pila, comenzando en la parte inferior

Con las capas creadas, los revisores obtienen diferencias pequeñas en lugar de una pared grande de código.

Si las dependencias están fuertemente integradas, pida revisiones que comiencen en la parte inferior de la pila, por lo que puede integrar los cambios en la pila antes de las revisiones posteriores.
Si necesita revisiones de personas independientes para diferentes capas, los revisores pueden trabajar en paralelo. Una persona puede revisar el modelo de datos mientras que otra revisa los puntos de conexión y ninguno de los trabajos a través de la revisión de toda la característica.

6. Iteración de los comentarios

Revise los comentarios sobre las capas individualmente, no toda la característica. Las pilas le permiten corregir la capa derecha en su lugar y llevar el cambio hacia arriba.

Revise la capa marcada por un revisor. Vaya a la rama derecha, realice el cambio y confírmelo allí.
Mantenga cada corrección en la capa a la que pertenece. Un cambio realizado en la rama incorrecta puede confundir y crear errores upstack.
Navegue por ramas con gh stack down, gh stack upo gh stack checkout BRANCH-NAME. A continuación, confirme los cambios, ejecute gh stack rebase --upstack para volver a base de las ramas anteriores y, a continuación gh stack push , para llevar los cambios a la pila.

7. Combinar desde la capa inferior

Una pila se combina en orden, empezando por la capa que apunta a la rama principal. Combine capas todas a la vez, o uno a uno, y GitHub vuelva a tener como destino automáticamente la siguiente capa para que apunte al principio.

Combine la pila una a la vez trabajando desde la parte inferior hacia arriba, o desde cualquier lugar de la pila y todas las ramas debajo de la solicitud de incorporación de cambios que combine se combinarán desde la parte inferior hacia arriba.
La diferencia de cada capa permanece exactamente igual con respecto a su elemento primario, solo los cambios base, lo que facilita la combinación de una capa a la vez sin afectar al trabajo o las revisiones en curso.
Use una cola de mezcla para que cada capa se combine en orden una vez que se apruebe y se superen sus comprobaciones. No es necesario esperar a toda la pila a la vez.

Una vez que se combina la capa superior, toda la característica ha llegado. Cada pieza se revisó de forma más eficaz como un cambio pequeño y deliberado en lugar de una solicitud de incorporación de cambios grande.