Apila código generado por IA en pull requests

Las solicitudes de incorporación de cambios grandes son difíciles de revisar y generan cuellos de botella, especialmente cuando la inteligencia artificial le ayuda a generar un gran volumen de código en un breve 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 revisar por encima el resultado, pasar por alto problemas o procrastinar y dejar la pull request hasta que se vuelva 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 las pull requests apiladas con agentes 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 GitHub Copilot CLI y la aptitud del gh-stack agente.

Prerequisites

Para usar la gh-stack skill con un agente, primero deberá instalar GitHub CLI y la extensión CLI de gh-stack. 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.
• GitHub Copilot CLI instalado y con sesión iniciada.

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

gh extension install github/gh-stack
gh skill install github/gh-stack

1. Diseñar un stack 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 el drywall. Cada capa creada depende de la inferior. Al final, un revisor debe poder leer las pull requests de abajo a arriba y seguir cómo va tomando forma la funcionalidad.

• Divida la funcionalidad en capas. Cada capa debe ser un único cambio coherente que pueda revisarse de forma independiente.
  • Mantenga cada capa lo suficientemente pequeña como para que su pull request sea una lectura rápida. Si parece que una capa necesita una descripción larga para revisarla, probablemente es demasiado grande.
  • Decida los límites usted mismo o trabaje con Copilot en un plan. En cualquier caso, define la estructura de la pila.
• Ordene las capas según sus dependencias. 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
  • Nivel 2: endpoints CRUD
  • Capa 3: middleware y guardias JWT
  • Capa 4: integración y pruebas unitarias

Ejemplos de indicaciones

• Propose a layered approach to add user authentication to this app. Order the layers by dependency, keeping each layer independently reviewable.
• Review my planned layers and flag any that are too large or that depend on a branch above them.

2. Cree primero la capa inferior.

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

• Informa a Copilot que vas a crear una pull request apilada y pídele que cree la primera capa en función de tu plan. El agente usa la gh-stack skill para crear la primera rama del stack.
• Si prefiere crear el stack usted mismo, créelo directamente con gh stack init, mediante un prefijo para mantener ordenados los nombres de rama, por ejemplo, gh stack init BRANCH-NAME-1.
• Revise el cambio generado antes de continuar. Un error en la capa inferior se propaga a cada rama por encima de ella, así que revísela antes de continuar.

Ejemplos de indicaciones

• Start the pr-stack and build only the first layer: the user data model and migration.
• Conduct a review of the generated code and confirm this branch contains only the data model and migration, and nothing that belongs in a later layer.

3. Apila cada nueva capa de código encima

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

• Pida Copilot que agregue la capa siguiente e implemente en el contexto de las capas inferiores. El agente agregará una rama a la parte superior del stack y hará commit de los cambios allí.
• Si desea agregar una rama usted mismo, use gh stack add BRANCH-NAME-NEXT.
• Si una capa comienza a crecer demasiado grande, 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, pida a Copilot que envíe su stack o, si quiere hacerlo usted mismo, use gh stack submit.
• Deje que cada solicitud de incorporación de cambios se entienda por sí sola. Un título centrado y una descripción concisa y significativa de la capa suele ser suficiente.

Ejemplos de indicaciones

• Add the next layer in a new branch on top: the CRUD endpoints that use the user model from the branch below.
• This branch is getting large. Suggest how it could be split into two independently reviewable layers.

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 branch antes de implicar a los compañeros de equipo. Los revisores deben recibir los cambios en los que ya confías.

• Ejecute las pruebas, linters y el análisis de código en cada rama. Deje que Copilot le ayude a comprobar cada capa con respecto a sus estándares antes de solicitar revisiones.
• Para conocer las técnicas para revisar los cambios generados por la INTELIGENCIA ARTIFICIAL exhaustivamente, consulte Revisión del código generado por IA.

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

Con las capas creadas, los revisores obtienen diffs pequeños 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, para que pueda 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 y ninguno de ellos recorre toda la funcionalidad.

6. Itera según los comentarios

Los comentarios de revisión recaen sobre las capas individualmente, no sobre toda la funcionalidad. Las pilas le permiten fijar la capa correcta en su sitio y propagar el cambio hacia las capas superiores.

• Pida Copilot que revise la capa que un revisor marcó. El agente se mueve a la rama de la derecha, realiza el cambio y hace commit allí. A continuación, reaplica el rebase a las capas superiores para que incorporen la corrección.
• Mantenga cada corrección en la capa a la que pertenece. Un cambio realizado en la rama incorrecta puede confundir y crear errores en niveles superiores de la pila.
• A medida que realice correcciones, pida Copilot que haga rebase de las ramas anteriores y propague los cambios.
• Si desea desplazarse por la pila usted mismo, navegue por ramificaciones con gh stack down, gh stack up o gh stack checkout BRANCH-NAME. A continuación, confirme los cambios y ejecute gh stack rebase --upstack para propagar los cambios hacia arriba en la pila.

Ejemplos de indicaciones

• A reviewer flagged that the auth service doesn't handle expired tokens. Fix that on BRANCH-NAME and test the changes.
• I've rebased the layers above onto this fix. Check that the branch with endpoints still works with the change and flag anything that needs updating.

7. Combinar desde la capa inferior

Un stack se fusiona en orden, empezando por la capa que apunta a tu rama principal. Combina capas todas a la vez, o una por una, y GitHub redirige automáticamente la siguiente capa para que apunte a main.

• Fusione la pila de una en una, trabajando desde la parte inferior hacia arriba, o desde cualquier lugar de la pila, y todas las ramas por debajo de la pull request que fusione se fusionarán desde la parte inferior 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.
• Use la combinación automática o una cola de fusión para que cada rama se combine tan pronto como se apruebe y se superen sus comprobaciones. No es necesario esperar a que se procese 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

• Revisión del código generado por IA
• Administración de pull requests apiladas