Modifications apportées au code de pile dans les demandes de tirage

Remarque

Cette fonctionnalité est disponible en préversion publique et peut être modifiée.

Les demandes de tirage volumineuses sont difficiles à examiner et à créer des goulots d’étranglement, en particulier lorsque vous générez un volume élevé de code dans un court délai. La qualité de l’examen dégrade également à mesure que la taille des demandes de tirage augmente. Les réviseurs peuvent ignorer le résultat, manquer des problèmes ou procrastinér et quitter la demande de tirage jusqu’à ce qu’elle augmente et développe des conflits de fusion.

Les demandes de tirage empilées conservent les modifications de code volumineuses pouvant être examinées.

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 guide tout au long de l’utilisation des demandes de tirage empilées pour créer une fonctionnalité dans des couches pouvant être examinées individuellement. Pour notre exemple, nous allons envisager comment ajouter l’authentification utilisateur à une application. Nous allons utiliser l’extension gh stack dans GitHub CLI.

Logiciels requis

Pour suivre ce tutoriel, vous devez installer GitHub CLI et l’extension gh stack . 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.
Dépôt GitHub vers lequel vous pouvez envoyer (push).

Dans GitHub CLI, installez l’extension gh stack .

gh extension install github/gh-stack

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

Une bonne pile est comme construire une maison : commencez par une fondation forte, cadrez les murs, installez le câblage, puis terminez la cloison sèche. Chaque couche dépend de celle ci-dessous. À la fin, un réviseur doit pouvoir lire les demandes de tirage de bas en haut et suivre le développement 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.
- Conservez chaque couche suffisamment petite pour que sa demande de tirage soit une lecture rapide. Si une couche a besoin d’une longue description à réviser, elle est probablement trop volumineuse.
- Décidez vous-même des limites. Vous possédez 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

2. Créez d’abord la couche inférieure

Démarrez la pile avec la base. Tout ce qui précède dépend de l’obtention de cette couche correctement.

Créez la pile et générez la première couche en fonction de votre plan. Créez-le avec gh stack init BRANCH-NAME-1, envisagez d’utiliser un préfixe pour conserver les noms de branche.
Passez en revue le changement vous-même avant de continuer. Une erreur dans la couche inférieure se propage à chaque branche au-dessus de celle-ci, donc donnez-lui un examen avant de passer en revue.

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.

Ajoutez la couche suivante et implémentez-la dans le contexte des couches ci-dessous. Ajoutez une branche en haut de la pile et gh stack add BRANCH-NAME-NEXT validez le travail là-bas.
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 de nouvelles branches pour chaque couche au fur et à mesure, de sorte que chaque branche reste un différences propre et autonome.
Lorsque vous êtes prêt à créer des demandes de tirage, envoyez votre pile avec gh stack submit.
Laissez chaque demande de tirage se tenir elle-même. Un titre ciblé et une description concise et explicite de la couche sont généralement suffisants.

4. Passez en revue les demandes de tirage vous-même avant de demander une révision

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

Exécutez vos tests, inters et analyse du code sur chaque branche pour vérifier chaque couche par rapport à vos normes avant de demander des révisions.

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

Avec les couches générées, les réviseurs obtiennent de petits différences au lieu d’un grand mur 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, et aucun travail n’est effectué en examinant l’ensemble de la fonctionnalité.

6. Itérer sur les commentaires

Passez en revue les commentaires sur les couches individuellement, et non sur l’ensemble de la fonctionnalité. Les piles vous permettent de corriger la couche appropriée en place et de porter le changement vers le haut.

Modifiez la couche avec indicateur de réviseur. Accédez à la branche droite, apportez la modification et validez-la là.
Conservez chaque correctif dans la couche auquel il appartient. Une modification apportée à la branche incorrecte peut confondre et créer des erreurs sur la pile.
Naviguer dans les branches avec gh stack down, gh stack upou gh stack checkout BRANCH-NAME. Ensuite, validez vos modifications, exécutez gh stack rebase --upstack pour rebaser les branches ci-dessus, puis gh stack push pour effectuer des modifications dans la pile.

7. Fusionner à partir de la couche inférieure

Une pile se fusionne dans l’ordre, en commençant par la couche pointant 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 la pile une à la fois qui fonctionne à partir du bas vers le haut, ou depuis n’importe où dans la pile, et toutes les branches sous la demande de tirage que vous fusionnez seront fusionnées à partir du bas vers le haut.
La différence de chaque couche reste exactement la même par rapport à son parent, mais uniquement les modifications de base, ce qui facilite la fusion d’une couche à la fois sans affecter le travail en cours ou les révisions.
Utilisez une file d’attente de fusion pour que chaque couche se fusionne dans l’ordre une fois qu’elle est approuvée et que ses contrôles passent. Vous n’avez pas besoin d’attendre sur l’ensemble de la pile à la fois.

Une fois la couche supérieure fusionnée, l’ensemble de la fonctionnalité a atterri. Chaque pièce a été examinée plus efficacement comme une petite modification délibérée plutôt qu’une demande de tirage volumineuse.