Cambios de código apilados en las solicitudes de extracción

Cree una serie de pull requests pequeñas y encadenadas que se puedan revisar rápidamente.

En este artículo

Las solicitudes de incorporación de cambios grandes son difíciles de revisar y crean 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 pull request. Los revisores pueden revisar por encima el resultado, pasar por alto problemas o procrastinar y dejar la pull request hasta que quede obsoleta y desarrolle conflictos de combinación.

Las pull requests apiladas permiten revisar cambios de código grandes.

Una pila es una serie de solicitudes de incorporación de cambios en el mismo repositorio donde cada solicitud de incorporación de cambios tiene como destino la rama de la solicitud de incorporación de cambios debajo de ella, formando una cadena ordenada que llega a una sola rama, normalmente la rama principal. En lugar de una solicitud de incorporación de cambios grande, obtendrá un conjunto de solicitudes de incorporación de cambios más pequeñas. Dado que cada solicitud de incorporación de cambios tiene su propia diferencia centrada, los compañeros de equipo pueden revisar y aprobar cada capa de forma independiente.

En este tutorial se explica cómo usar pull requests 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 al que puede hacer push.

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

Un buen stack es como construir una casa: empezar con una base fuerte, enmarcar las paredes, instalar cableado y luego terminar los paneles de yeso. Cada capa se basa en la inferior. Al final, un revisor debe poder leer las pull requests de abajo a arriba y seguir el desarrollo de la característica.

  • Divida la funcionalidad en capas. Cada capa debe ser una única modificación coherente que se pueda revisar por sí misma.
    • Mantenga cada capa lo suficientemente pequeña como para que su pull request se lea rápido. Si una capa parece requerir una descripción larga para revisarla, probablemente es demasiado grande.
    • Defina usted mismo los límites. Defines la forma de la pila.
  • Ordene las capas por dependencia. Los cambios fundamentales van en la parte inferior. Todo lo que depende de ellos sube más. Para la autenticación, puede ser:
    • Capa 1: modelo de datos y migración
    • Capa 2: endpoints CRUD
    • Capa 3: middleware y guardas JWT
    • Capa 4: pruebas de integración y unitarias

2. Cree primero la capa inferior.

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

  • Cree la pila y compile la primera capa según su 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. Apila cada nueva capa de código en la parte superior

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

  • Agregue la capa siguiente e implemente en el contexto de las capas inferiores. Agregue una rama a la parte superior de la pila con gh stack add BRANCH-NAME-NEXT y haz commit del trabajo allí.
  • Si una capa comienza a crecer demasiado, considere si se ha desviado de su plan o si realmente necesita dos capas en lugar de una.
  • Cree nuevas ramas para cada capa a medida que avanza, por lo que cada rama siga siendo un diff limpio e independiente.
  • Cuando esté listo para crear pull requests, envíe el stack con gh stack submit.
  • Deje que cada solicitud de incorporación de cambios pueda entenderse por sí sola. Un título centrado y una descripción concisa y significativa de la capa suele ser suficiente.

4. Revise las pull requests antes de solicitar una revisión.

Cada capa es pequeña, lo que facilita la auto-revisión también. Revise cada rama antes de involucrar al equipo. Los revisores deben recibir los cambios en los 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 un gran bloque de código.

  • Si las dependencias están fuertemente integradas, pida revisiones que comiencen en la parte inferior de la pila, para poder integrar los cambios en la pila antes de las revisiones posteriores.
  • Si necesita revisiones de personas distintas para diferentes capas, los revisores pueden trabajar en paralelo. Una persona puede revisar el modelo de datos mientras que otra revisa los endpoints, sin que ninguna tenga que revisar toda la funcionalidad.

6. Itera según los comentarios

Los comentarios de revisión se aplican a las capas de forma individual, no a toda la función. Las capas apiladas le permiten fijar la capa correcta en su sitio y propagar el cambio hacia arriba.

  • Revise la capa que señaló un revisor. Vaya a la rama correcta, realice el cambio y haga commit allí.
  • Mantenga cada corrección en la capa a la que pertenece. Un cambio realizado en la rama incorrecta puede confundir y crear errores en ramas superiores.
  • 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 rebasar 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 tu rama principal. Combina las capas todas a la vez, o una a una, y GitHub redirige automáticamente la siguiente capa para que apunte a main.

  • Fusione la pila de una en una empezando desde abajo hacia arriba, o desde cualquier punto de la pila; todas las ramas situadas por debajo del pull request que fusione se fusionarán de abajo hacia arriba.
  • La diferencia de cada capa permanece exactamente igual con respecto a su capa padre, solo cambia la base, lo que facilita la combinación de una capa a la vez sin afectar al trabajo o las revisiones en curso.
  • Usa una cola de fusión para que cada capa se combine en orden una vez que se apruebe y se superen sus comprobaciones. No es necesario esperar a que se complete toda la pila de una vez.

Una vez que se combina la capa superior, toda la funcionalidad ya se ha integrado. Cada pieza se revisó de forma más eficaz como un cambio pequeño y deliberado en lugar de un pull request grande.

Lectura adicional