À propos des pull requests empilées

À propos des pull requests empilées

Les demandes de tirage empilées sont deux ou plusieurs demandes de tirage dans le même référentiel, où :

• La première pull request, ou celle située en bas, cible la branche principale de la pile — généralement la branche par défaut de votre dépôt, telle que main, même s’il peut s’agir de n’importe quelle branche, comme une branche de publication.
• Chaque pull request suivante cible la branche de la pull request située en dessous.

   ┌── feat/frontend     → PR #3 (base: feat/api-endpoints)  ← top
  ┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer     → PR #1 (base: main)               ← bottom
main (default base branch)

Les branches empilées forment une chaîne de dépendances, où chaque branche s’appuie sur celle-ci. Les modifications fondamentales telles que les types partagés et le schéma de base de données vont dans les branches inférieures, et le code qui en dépend, tels que les itinéraires d’API et les composants de l’interface utilisateur, vont dans des branches supérieures.

Chaque pull request d’une pile représente une modification distincte, pouvant être examinée, composée d’un ou de plusieurs commits. Vous pouvez examiner et retravailler chaque pull request indépendamment, et chacune n’affiche que le diff de sa couche ainsi que les modifications entre sa branche et la branche inférieure.

Principe clé : si le code d’une couche dépend du code d’une autre, la dépendance doit se trouver dans la même branche ou une branche inférieure. Créez une nouvelle branche lorsque vous commencez une autre tâche qui dépend de ce que vous avez déjà fait. Par exemple, lorsque vous passez du back-end au front-end, de la logique métier aux tests, ou lorsque la branche actuelle est déjà assez volumineuse pour être revue.

Pourquoi utiliser GitHub des demandes de tirage empilées

Terminer un changement et passer directement à la suivante

Les pull requests empilées vous permettent d’ouvrir une nouvelle pull request sur une pull request encore ouverte. Pendant un projet volumineux, votre prochaine modification peut dépendre du travail qui n’a pas encore été fusionné. Au lieu d’attendre qu’elle soit fusionnée, avec une stack, vous pouvez continuer à développer.

Avec chaque pull request d’une pile où chacune contient une modification ciblée, les relecteurs voient un diff réduit à chaque niveau au lieu d’une pull request volumineuse. Les pull requests de plus petite taille sont plus rapides à relire, moins susceptibles d’être survolées, et moins susceptibles de devenir obsolètes et d’entraîner des conflits de fusion.

Adapté au développement à grande échelle

Lorsque vous générez beaucoup de code à la fois, souvent à l’aide d’agents IA, une stack donne à chaque modification sa place. Un agent effectue une tâche, puis démarre la tâche suivante qui s’appuie dessus. Cette séquence correspond directement à une pile : une pull request par tâche, chacune basée sur la précédente. Les Stacks vous permettent de consigner ces dépendances de manière explicite au lieu de combiner des modifications sans lien dans une seule branche.

Avantages de l’utilisation de pull requests empilées dans GitHub

Sans les pull requests empilées, découper une modification importante en pull requests plus petites et dépendantes entraîne un surcroît de travail :

• Gestion des branches. Le rebasage et la synchronisation des branches dans des pull requests dépendantes sont fastidieux et source d’erreurs.
• Règles et CI. Les règles de protection des branches et les vérifications d’intégration continue (CI) ne se déclenchent souvent que pour la pull request située tout en bas de la chaîne, ce qui rend difficile de connaître l’état réel des autres.
• Passez en revue le contexte. Examiner un seul changement isolément du reste de la pile peut réduire la qualité de la revue.

Les pull requests empilées résolvent ces problèmes en traitant la chaîne de pull requests comme un ensemble cohérent, tout en gardant chaque couche réduite et ciblée.

Rebase

Le rebasage est la partie la plus délicate de l’utilisation des piles, et GitHub le gère automatiquement. Vous pouvez déclencher une rebase en cascade côté serveur à partir de la requête pull ou exécuter une rebase en cascade locale avec l’extension gh stack dans GitHub CLI. Lorsque vous fusionnez une pull request en bas de la pile, les branches restantes sont automatiquement rebasées afin que la pull request suivante cible la branche de base par défaut.

Où pouvez-vous utiliser les pull requests empilées

Les pull requests empilées sont disponibles dans les sections suivantes :

• GitHub CLI
• Site web GitHub
• GitHub Mobile
• Prise en charge programmatique par le biais de Webhooks, d’API REST et de GraphQL
• Pour les agents, via la gh-stack compétence

Dans GitHub CLI

L’extension gh stack dans GitHub CLI gère le flux de travail de développement local. Vous pouvez créer et suivre des branches dans le bon ordre de dépendance, garder les branches rebasées, pousser des branches, créer et lier des pull requests, et naviguer entre les couches. Consultez « Commandes CLI des demandes de tirage empilées ».

Sur le site Web GitHub

Lorsqu’une pull request fait partie d’une pile, vous verrez :

• Une icône de pile en haut de la pull request avec un nombre indiquant la couche que vous consultez.
• Une carte empilée s’affiche dans la zone de fusion. Il affiche chaque pull request de la pile et son état, et vous permet d’accéder à n’importe quel niveau en un clic. La branche principale (branche de base par défaut) se trouve en bas, chaque pull request de la pile ciblant la branche de la pull request située juste en dessous.

Prise en charge programmatique par le biais de Webhooks, d’API REST et de GraphQL

Les pull requests empilées sont accessibles par programmation, afin que vous puissiez les intégrer à vos propres outils, automatisations et tableaux de bord :

• Les webhooks incluent un objet stack dans les charges utiles d’événement pull_request, afin que votre automatisation puisse réagir lorsqu’une pull request rejoint une stack, s’y déplace ou la quitte.
• L’API REST lit l’appartenance d’une pull request à une pile et fournit des points de terminaison pour lister, créer, étendre et dissoudre des piles.
• L’API GraphQL expose des champs en lecture seule stack dans une pull request pour interroger la pile et la position de la pull request dans cette pile.

Règles, CI et fusion

Règles et application de CI

Les pull requests en pile prennent en charge les flux de travail GitHub Actions.

Les exigences de fusion de toute pull request dans la pile sont déterminées par la branche de base de la pull request du bas, généralement main.

• Les règles de protection de branche, telles que les validations des CODEOWNERS, s’appliquent à chaque pull request de la pile, y compris aux pull requests intermédiaires de la pile qui ne ciblent pas directement votre branche par défaut.
• Les vérifications CI déclenchées par des pull requests sur votre branche par défaut s’exécutent pour toutes les pull requests de la pile, et pas seulement pour celle du bas.

Cela garantit que chaque couche de la pile répond à la même barre de qualité avant de pouvoir fusionner.

Fusion

Vous pouvez fusionner l’ensemble de votre pile, une demande de tirage unique ou une partie de la pile couvrant plusieurs demandes de tirage. La pile entière n’a pas besoin d’être fusionnée en une seule fois, mais les pull requests doivent être fusionnées de bas en haut.

• Fusionnez toute la pile en une seule fois en fusionnant la pull request en haut de la pile. Chaque pull request en dessous l’inclut.
• Fusionnez une partie de la pile en fusionnant une pull request au milieu de la pile. Les pull requests situées en dessous sont elles aussi fusionnées, et celles situées au-dessus restent ouvertes et sont automatiquement redirigées vers la branche de base de la pile.

Stacks prennent en charge les méthodes de fusion commit de fusion, squash et rebase, et sont compatibles avec la file d’attente de fusion. L’historique des commits obtenu est le même que celui obtenu en fusionnant chaque pull request une par une, en partant du bas.

Étapes suivantes

• Démarrage rapide pour les demandes de tirage empilées
• Déployer des demandes de tirage empilées dans votre organisation