Empilez le code généré par l’IA dans les pull requests

Les pull requests de grande taille sont difficiles à examiner et créent des goulots d’étranglement, en particulier lorsque l’IA vous aide à générer un volume élevé de code en peu de temps. La qualité de la revue se dégrade également à mesure que la taille des pull requests augmente. Les réviseurs peuvent survoler le résultat, passer à côté de problèmes ou remettre la vérification à plus tard et laisser la demande de tirage de côté jusqu’à ce qu’elle devienne obsolète et finisse par présenter des conflits de fusion.

Les pull requests empilées permettent de garder les modifications importantes du code faciles à relire.

Une pile est une série de demandes d’extraction dans le même référentiel où chaque demande de tirage cible la branche de la demande de tirage sous celle-ci, formant une chaîne ordonnée qui atterrit sur une branche unique, généralement votre branche principale. Au lieu d’une demande de tirage volumineuse, vous obtenez un ensemble de demandes de tirage plus petites. Étant donné que chaque demande de tirage a ses propres différences ciblées, les collègues peuvent examiner et approuver chaque couche indépendamment.

Ce tutoriel vous explique comment utiliser des pull requests empilées avec des agents pour développer une fonctionnalité en couches pouvant être examinées individuellement. Pour notre exemple, nous allons envisager comment ajouter l’authentification utilisateur à une application. Nous allons utiliser GitHub Copilot CLI et la compétence de l’agent gh-stack .

Prerequisites

Pour utiliser la gh-stack compétence avec un agent, vous devez d’abord installer GitHub CLI et l’extension gh-stack CLI. Vous aurez besoin des éléments suivants :

• GitHub CLI (gh) 2.90.0 ou version ultérieure, et Git 2.20 ou version ultérieure.
  • Authentifiez-vous GitHub CLI avec gh auth login.
• Un dépôt GitHub vers lequel vous pouvez pousser.
• GitHub Copilot CLI installé et connecté.

Dans GitHub CLI, installez l’extension et la compétence gh-stack.

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

1. Définir une pile avant de générer du code

Une bonne pile est comme construire une maison, commencer par des fondations robustes, monter les murs, installer le câblage, puis terminer les cloisons sèches. Chaque couche créée dépend de celle ci-dessous. Au final, un réviseur doit pouvoir lire les demandes de tirage de bas en haut et suivre la mise en place progressive de la fonctionnalité.

• Fractionnez la fonctionnalité en couches. Chaque couche doit être un changement unique et cohérent qui peut être examiné par lui-même.
  • Veillez à garder chaque couche suffisamment petite pour que sa pull request se lise rapidement. Si une couche semble nécessiter une longue description pour être examinée, elle est probablement trop grosse.
  • Définissez vous-même les limites, ou élaborez un plan avec Copilot. De toute façon, vous maîtrisez la forme de la pile.
• Triez les couches par dépendance. Les changements fondamentaux vont en bas. Tout ce qui dépend d’eux va plus haut. Pour l’authentification, il peut s’agir des points suivants :
  • Couche 1 : modèle de données et migration
  • Couche 2 : points de terminaison CRUD
  • Couche 3 : middleware JWT et gardes
  • Couche 4 : tests unitaires et d’intégration

Exemples d’invites

• 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. Créez d’abord la couche inférieure

Démarrez la pile avec les fondations. Tout ce qui précède dépend de la bonne conception de cette couche.

• Informez Copilot que vous allez créer une pull request empilée et demandez-lui de créer la première couche à partir de votre plan. L’agent utilise la gh-stack compétence pour créer la première branche de la pile.
• Si vous préférez créer la pile vous-même, créez-la directement avec gh stack init, en utilisant un préfixe afin de garder les noms de branches bien organisés, par exemple : gh stack init BRANCH-NAME-1
• Passez en revue le changement généré vous-même avant de continuer. Une erreur dans la couche du bas se répercute sur toutes les branches au-dessus, alors examinez-la attentivement avant de continuer.

Exemples d’invites

• 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. Empilez chaque nouvelle couche de code en haut

Avec la base en place, générez le reste de la fonctionnalité une couche à la fois.

• Demandez Copilot à ajouter la couche suivante et à l’implémenter dans le contexte des couches ci-dessous. L’agent ajoutera une branche au sommet de la pile et validera les modifications sur celle-ci.
• Si vous souhaitez ajouter une branche vous-même, utilisez gh stack add BRANCH-NAME-NEXT.
• Si une couche commence à croître trop grande, déterminez si elle a dérivé en dehors de son plan ou si vous avez réellement besoin de deux couches au lieu d’une.
• Créez des branches pour chaque couche au fur et à mesure, afin que chaque branche reste un ensemble de changements propre et autonome.
• Lorsque vous êtes prêt à créer des pull requests, demandez à Copilot de soumettre votre pile, ou, si vous souhaitez le faire vous-même, utilisez gh stack submit.
• Que chaque pull request se suffise à elle-même. Un titre ciblé et une description concise et explicite de la couche sont généralement suffisants.

Exemples d’invites

• 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. Vérifier vous-même les demandes de tirage avant de demander une révision

Chaque couche est petite, ce qui facilite également l’auto-révision. Passez en revue chaque branche avant d’impliquer vos collègues. Les réviseurs doivent recevoir des modifications que vous approuvez déjà.

• Exécutez vos tests, linters et analyses du code sur chaque branche. Laissez Copilot vous aider à vérifier chaque couche selon vos normes avant de demander des relectures.
• Pour connaître les techniques d’examen approfondi des modifications générées par l’IA, consultez Passer en revue le code généré par l’IA.

5. Demander des révisions pour la pile, en commençant par le bas

Avec les couches générées, les réviseurs voient des petits différences au lieu d’un grand morceau de code.

• Si les dépendances sont fortement intégrées, demandez des révisions en commençant au bas de la pile. Vous pouvez donc intégrer les modifications de la pile avant les révisions suivantes.
• Si vous avez besoin de révisions de personnes distinctes pour différentes couches, les réviseurs peuvent travailler en parallèle. Une personne peut passer en revue le modèle de données tandis qu’une autre examine les points de terminaison, sans que l’une ou l’autre ait à parcourir l’ensemble de la fonctionnalité.

6. Itérer sur les commentaires

Les retours de révision s’appliquent à chaque couche individuellement, et non à la fonctionnalité dans son ensemble. Les piles vous permettent d’apporter la correction directement à la bonne couche et de propager la modification vers les couches supérieures.

• Demandez à Copilot de réviser la couche qu’un réviseur a signalée. L’agent se déplace vers la branche droite, apporte la modification et la valide là. Ensuite, il rebase les couches supérieures pour qu’elles intègrent la correction.
• Conservez chaque correctif dans la couche auquel il appartient. Une modification effectuée sur la mauvaise branche peut prêter à confusion et créer des erreurs plus haut dans la pile.
• Lorsque vous apportez des correctifs, demandez Copilot à rebaser les branches ci-dessus et à propager les modifications.
• Si vous souhaitez vous déplacer vous-même dans la pile, naviguez entre les branches avec gh stack down, gh stack up ou gh stack checkout BRANCH-NAME. Ensuite, validez vos modifications et exécutez gh stack rebase --upstack pour faire remonter les modifications dans la pile.

Exemples d’invites

• 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. Fusionner à partir de la couche inférieure

Une pile est fusionnée dans l’ordre, en commençant par la branche qui pointe vers votre branche principale. Fusionnez toutes les couches en même temps, ou un par un, et GitHub cible automatiquement la couche suivante pour qu’elle pointe vers la partie principale.

• Fusionnez les éléments de la pile un par un en partant du bas vers le haut, ou à partir de n’importe quel endroit de la pile ; toutes les branches situées sous la pull request que vous fusionnez seront alors fusionnées du bas vers le haut.
• La différence de chaque couche reste exactement la même par rapport à sa couche parente ; seule la base change, ce qui permet de fusionner une couche à la fois sans affecter le travail en cours ni les revues.
• Utilisez la fusion automatique ou une file d’attente de fusion pour que chaque couche fusionne dès qu’elle est approuvée et que ses vérifications réussissent. Vous n’avez pas besoin d’attendre toute la pile en une fois.

Une fois la couche supérieure fusionnée, la fonctionnalité entière est intégrée. Chaque élément a été évalué plus efficacement lorsqu’il prenait la forme d’un petit changement intentionnel plutôt que d’une pull request de grande ampleur.

Lectures complémentaires

• Passer en revue le code généré par l’IA
• Gestion des demandes de tirage empilées