PRs empilés (Stacked PRs)

Que fait PRs empilés (Stacked PRs) ?

Le budget de taille

Visez environ 300 lignes modifiées par PR, avec 500 comme plafond. À cette taille, un humain peut garder l'ensemble de la modification en tête pour une revue rapide, et les agents de revue reviennent avec des retours propres et spécifiques au lieu de survoler.

Ce qui compte : le code écrit à la main et les tests.

Ce qui ne compte pas : les fichiers de verrouillage (lockfiles), le code généré (migrations, génération de code, sortie OpenAPI), les snapshots, les fixtures et les fichiers fournis (vendored). Ils sont survolés, pas lus. Listez les fichiers générés dans le corps de la PR pour que le réviseur sache quoi ignorer.

Divisez avant d'écrire, pas après. La division est décidée dans le plan (voir coding-process). Si une étape prévue dépasse 500, re-planifiez-la. Points de division courants :

• Les tests peuvent être leur propre étape. Par exemple, la logique avec des tests unitaires et d'intégration, puis l'interface utilisateur avec des tests E2E.
• Schéma ou modèle de données, puis le service qui l'utilise, puis la surface API, puis l'interface utilisateur.
• Un refactoring qui simplifie la modification, puis la modification.
• Une mise à jour de documentation trop volumineuse pour être incluse devient une étape dédiée en haut de la pile.

Les modifications véritablement indivisibles, comme une migration cohérente ou un renommage sur 80 fichiers, peuvent dépasser la limite. Le corps de la PR dit pourquoi et indique au réviseur la partie qui nécessite une lecture attentive.

Les commits atomiques s'appliquent toujours à l'intérieur de chaque PR. Le budget est par PR, et ne remplace pas une bonne hygiène de commits.

Empilement

Un travail en plusieurs étapes est livré sous forme de pile de PRs, jamais comme une seule branche portant tout le plan. Chaque PR représente une étape et cible la branche de l'étape précédente, pas main. Ainsi, chaque diff que le réviseur voit correspond uniquement à la modification de cette étape, et une étape risquée (une migration, un changement d'authentification) peut être révisée et annulée indépendamment.

• Créez chaque branche à partir de la tête de l'étape précédente. Seule la PR du bas cible main :

  gh pr create --base <branche-etape-precedente>
  

• Notez la position dans le corps de chaque PR (Empilé sur #123) afin qu'un réviseur qui ouvre une PR dans le désordre sache ce qu'il regarde.
• Fusionnez de bas en haut. Lorsqu'une branche de base change (une correction de revue, ou la fusion de la base), rebasez les branches au-dessus et force-push celles-ci. Force-push vos propres branches de pile non fusionnées est courant. Force-push main ou une branche partagée ne l'est jamais.
• Après qu'une PR de la pile a fusionné, synchronisez le reste sur la nouvelle base avant de commencer l'étape suivante.
• Les corrections issues d'une revue ou d'une vérification sur une surface UI sont livrées comme une nouvelle étape au-dessus, de sorte que la construction et les corrections restent séparément révisables.
• Les outils d'empilement comme gh stack, Graphite ou git-town sont facultatifs. Git pur et gh suffisent.

Revue séquentielle

Révisez une pile une étape à la fois. Demandez une revue au réviseur du projet (voir les barrières de projet dans AGENTS.md) uniquement sur la PR du bas, puis :

1. Demandez une revue sur cette seule étape.
2. Traitez chaque commentaire (voir ci-dessous).
3. Redemandez une revue, et répétez jusqu'à ce que l'étape soit approuvée.
4. Alors seulement demandez une revue sur l'étape suivante.

Ne demandez pas une revue sur toute la pile en une fois. Un commentaire sur l'étape 1 peut invalider des commentaires déjà écrits sur les étapes 2 à 5, et la revue séquentielle maintient l'effort du réviseur limité.

Si une étape stagne (pas de retour de revue, ou un commentaire nécessitant une décision produit), signalez-la et continuez à construire localement les étapes supérieures qui n'en dépendent pas.

Traitement des retours de revue (toute PR, empilée ou non)

• Vérifiez techniquement chaque commentaire avant d'agir. Lisez le code qu'il cible et reproduisez le problème si possible.
• Corrigez-le, ou contestez avec des arguments. Les réviseurs, humains ou bots, ont régulièrement tort en toute confiance. Faire une mauvaise modification pour être agréable est pire que de discuter. Pas d'accord factice.
• Jugez les commentaires par leur probabilité réelle. Contestez les corrections pour des scénarios qui ne peuvent pas se produire en pratique, et les suggestions qui ajoutent de la complexité sans gain réel.
• N'ajoutez pas de tests qui ne peuvent pas échouer. Un test qui passe que le bug existe ou non est du bruit. Lancez-le d'abord avec le code défaillant (voir testing).
• Répondez à chaque commentaire pour que le réviseur puisse voir ce qu'il en est : corrigé dans quel commit, ou pourquoi pas.