Explorateur de PR
Produire un document qui enseigne à un collègue une modification : ce qui n'allait pas ou manquait, comment le système fonctionne autour, ce que fait le changement, et comment nous savons qu'il fonctionne.
Arguments
- Cible : un numéro ou une URL de PR, ou rien.
- Avec une PR et l'interface
ghdisponible, récupérez les détails avecgh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,fileset le diff avecgh pr diff <url>. Lisez le code environnant au commit de tête de la PR (git show <headRefOid>:<path>), pasHEADlocal. - Sans PR, ou sans
gh: expliquez le changement local. Utilisezgit diff <base>...HEADpour les commits etgit diffplusgit statuspour le travail non commité, où<base>est la branche par défaut ou le premier commit.
- Avec une PR et l'interface
--local: utilisez le checkout local même lorsqu'une PR existe (travail non poussé). Notez sur la page qu'elle reflète les modifications locales.--concise: une version courte qui se lit en deux minutes environ. Au maximum un visuel, 3 extraits de code, pas de table des matières, 1 à 3 phrases par section.--md: écrivez en Markdown au lieu de HTML (fichier par défautHANDOVER.mdà la racine du dépôt, sauf si l'utilisateur en nomme un). Utilisez ceci pour les passations et lorsqu'un navigateur n'est pas pratique.
Public et voix
- Le lecteur est un ingénieur junior de l'équipe. Utilisez des phrases courtes, des verbes simples, une idée par paragraphe.
- Ne définissez pas les bases (REST, SQL, JWT, hooks React) et n'utilisez pas d'analogies non techniques. Restez technique, avec de vrais noms de modules, fonctions, routes et champs, et de vrais nombres.
- Simplifiez la rédaction, pas le contenu. Expliquez un appel de bibliothèque ou un motif inhabituel là où il apparaît.
- Rédigez comme une version finale. Décrivez directement l'état actuel. Pas de journal des modifications ni de formulation « nous pensions plus tôt ».
- Soyez honnête sur la certitude. Étiquetez les affirmations non prouvées « probable, pas encore confirmé ».
Portée : expliquer le changement, pas le diff
- Choisissez les fichiers qui racontent l'histoire, et à l'intérieur seulement les lignes qui comptent.
- Utilisez 1 à 3 extraits par fichier, chacun de moins de ~25 lignes, avec
...pour les parties élidées. Donnez à chacun le chemin du fichier et 2 à 4 phrases sur ce qu'il fait et pourquoi. - Pour un correctif, montrez le code qui a causé le bogue et le diff du correctif.
- Ordonnez le code selon le flux d'exécution, pas l'ordre du diff.
- Sautez les changements de plomberie, les renommages et le formatage. Mentionnez-les en une ligne si un relecteur les verra dans le diff.
1. Comprendre le changement
- Lisez le diff et le code environnant. Décidez du mode :
- Fonctionnalité : nouveau comportement ou refactorisation importante.
- Correctif de bogue : un symptôme, une cause racine et un correctif.
- Trouvez la dernière exécution de vérification : commande de test et résultats, et idéalement la preuve qu'un nouveau test de régression échoue sans le correctif et passe avec. Si cette preuve n'existe pas et qu'il est peu coûteux de la produire, faites-le :
git stash push -- <fichiers sources>, exécutez le test, puisgit stash pop. Cherchez également une vérification manuelle ou de bout en bout (sortie CLI, requête, capture d'écran). Montrez uniquement la dernière exécution de chaque. - Utilisez les résultats de la conversation (analyse de cause racine, rapport QA, ticket) lorsqu'ils existent.
2. Structure
Chaque document commence par une ligne d'en-tête (dépôt · PR #n · ticket, ou dépôt · modifications locales), un titre en langage clair et un chapô de 1 à 2 phrases.
Correctif de bogue
- Ce qui n'a pas fonctionné : le symptôme, où il a été vu, ce qui a été écarté.
- Cause racine : l'endroit exact où les données ou le flux se brisent (
fichier:ligne), avec un visuel si cela aide. - Le code qui l'a causé : un ou deux extraits.
- Le correctif : un extrait de diff et pourquoi il fonctionne. Nommez les effets secondaires qu'il corrige également.
- Comment nous le savons : un test de régression qui échoue avant et passe après, les résultats de la suite complète, une vérification manuelle.
- Enseignements : 2 à 4 leçons qu'un junior peut réutiliser ailleurs.
Fonctionnalité
- Pourquoi : le problème ou l'objectif, avec des preuves.
- Où cela se situe : contexte d'architecture ou de module (diagramme), plus ce qui est intentionnellement inchangé.
- Comment cela fonctionne : étapes ou organigramme lié aux cartes de code.
- Visite guidée du code : une carte par fichier important, dans l'ordre du flux.
- Comportement à connaître : cas limites, états, modes de défaillance (un tableau s'il y en a plus de 3).
- Vérification : seulement la dernière exécution.
- Enseignement pour le relecteur : le modèle mental en 2 à 3 lignes, et où regarder le plus attentivement dans le diff.
Ajouts pour la passation (toujours inclus avec --md ; facultatif en HTML) :
- Comment exécuter / tester : commandes exactes.
- Hypothèses faites : décisions prises là où le cahier des charges était silencieux, et pourquoi.
- Questions ouvertes pour le métier : classées par impact.
- Risques et retour arrière : ce qui pourrait mal tourner en production et comment revenir en arrière.
- Prochaines étapes : ce que vous feriez avec plus de temps.
Concise : seulement Ce qui n'a pas fonctionné / Quoi et pourquoi, Cause racine / Comment cela fonctionne, Le correctif / Code clé, et Comment nous le savons.
3. Visuels : seulement lorsqu'ils expliquent quelque chose que le texte ne peut pas
| Contenu | Utilisation |
|---|---|
| Architecture de module ou de service, qui appelle qui, séquence de requêtes | flowchart / sequenceDiagram Mermaid (≤ ~12 nœuds) |
| Une branche qui se comporte différemment avant et après | Tableau avant/après ou petit SVG statique |
| Données passant par des étapes, valeurs éliminées par un filtre | Un tableau d'exemples d'entrées → sorties, avant vs après |
| États, commandes, risques, contrats | Tableaux |
En Markdown, utilisez des blocs ```mermaid (GitHub les rend). N'ajoutez des animations que si l'utilisateur le demande.
4. Construction
- HTML : partez de
references/page-template.html(autonome, mode clair et sombre, Mermaid et highlight.js depuis un CDN). Sauvegardez dans.pr-review/<nom>.html, nommé d'après le ticket ou la PR, oulocal-<description-courte>.Gardez-le hors de git : sigit check-ignore -q .pr-review/échoue, ajoutez.pr-review/à.git/info/exclude. Ne modifiez pas.gitignoresauf demande explicite.- Extraits de code :
<pre><code class="language-<lang>">…</code></pre>, échappés en HTML. Pour un diff de correctif, utilisezlanguage-diffavec les lignes-/+. - Mermaid :
<pre class="mermaid">…</pre>. Ne codez jamais les couleurs en dur.
- Extraits de code :
- Markdown (
--md) : Markdown standard de type GitHub, même structure, pas de HTML.
5. Vérifier une fois
- HTML : si un outil de navigation est disponible, ouvrez la page une fois en largeur de bureau et une fois à ~400px. Vérifiez que Mermaid s'affiche et que le code est mis en évidence, corrigez ce que vous avez vu en un passage, et ne bouclez pas. Sinon, dites qu'elle n'a pas été prévisualisée et donnez la commande pour l'ouvrir (
opensur macOS,startsur Windows,xdg-opensur Linux). - Relisez chaque
fichier:ligne, nombre et commande sur la page par rapport au code. Les faits doivent être exacts.
6. Rapporter
Répondez avec :
- le chemin du fichier
- le mode, et les sections couvertes
- les visuels utilisés et ce que chacun explique
- quelle exécution de vérification le document montre
- tout ce qui est étiqueté « pas encore confirmé »
Ne modifiez jamais le corps d'une PR, ne postez pas de commentaire et ne poussez rien sans demander au préalable.