TrackerJo/pr-description

Descriptions de PR en anglais simple

Rédigez pour un mainteneur qui doit comprendre le changement rapidement. Une bonne description répond à trois questions dans son premier écran :

1. Qu'est-ce qui manquait ou était incorrect ?
2. Pourquoi cela devait-il changer ?
3. Qu'est-ce qui est vrai maintenant ?

Lisez le diff réel, le corps actuel de la PR, les commits, les tests et l'état de la PR avant d'écrire. L'ancien corps et les titres de commit décrivent l'intention, pas la preuve. Ne dites pas que des tests manuels, un déploiement ou un comportement en production ont été réalisés, sauf si l'auteur l'a confirmé.

Ouverture obligatoire : Ce qui a changé et pourquoi

Chaque description de PR doit commencer par une section ## What Changed and Why appartenant au contributeur, immédiatement après la section ## Status appartenant au moniteur lorsque Status est présent. Ceci est obligatoire, pas une option de formatage.

Utilisez trois courts paragraphes étiquetés, dans cet ordre :

• Issue : la défaillance réelle de l'utilisateur ou de l'opérateur, ou le comportement manquant.
• Why this change was necessary : pourquoi cette défaillance était importante et pourquoi la limite choisie est nécessaire.
• New status quo : le comportement concret après cette PR.

Gardez chaque paragraphe étiqueté à une ou deux phrases. Un mainteneur doit pouvoir répondre à « que s'est-il passé dans cette PR ? » à partir de cette section uniquement. Ne commencez pas par des détails d'implémentation, une conception supprimée ou une réécriture de l'historique.

Lorsque vous examinez une ouverture inadéquate, donnez un remplacement concret ou un plan concis de trois paragraphes adapté au diff réel. Ne vous contentez pas de dire qu'il est verbeux, peu clair ou qu'il nécessite une meilleure explication.

Utilisez ce modèle pour la plupart des PR :

## What Changed and Why

**Issue :** [La défaillance réelle de l'utilisateur ou de l'opérateur, ou le comportement manquant.]

**Why this change was necessary :** [Pourquoi cela était important et pourquoi cette limite est nécessaire.]

**New status quo :** [Le comportement concret après cette PR.]

## After merge

[Seules les actions réelles restantes pour l'opérateur ou le relecteur. Omettre cette section s'il n'y en a aucune.]

## Verification

[Indiquez uniquement les vérifications manuelles confirmées et les vérifications véritablement post-fusion.]

Commencez par le fond. Ne reformulez pas le titre de la PR, n'ajoutez pas d'introduction ou n'écrivez pas de résumé qui répète le paragraphe suivant.

Ce qu'il faut conserver

• Un état final clair par changement matériel. Un lecteur parcourant la première phrase de chaque paragraphe ou puce doit comprendre ce qui change après la fusion.
• Décisions réelles. Ne nommez une alternative rejetée que lorsqu'elle affecte le comportement du produit, le risque ou un coût significatif. Dites ce qui a été choisi et pourquoi en une phrase. Ne créez pas artificiellement une étiquette « Key decision ».
• Faits opérationnels. Mentionnez les migrations, les rattrapages, les tâches planifiées, les intégrations, les secrets, l'ordre de déploiement et le comportement en cas d'échec lorsqu'un relecteur ou un opérateur doit agir en conséquence.
• Vérification honnête. Séparez ce que quelqu'un a effectivement vérifié manuellement du travail qui doit vraiment attendre après la fusion. Ne listez pas les commandes de lint, build, CI ou test. Les tests peuvent être mentionnés en anglais simple lorsqu'ils couvrent un comportement significatif.
• Appels ouverts. Incluez uniquement les décisions non résolues que le relecteur doit prendre. Mettez la question en premier, puis une recommandation et son coût. Omettez la section lorsqu'il n'y a rien à décider.

Preuve obligatoire pour les systèmes modifiés

Une description est incomplète lorsqu'elle modifie un système orienté utilisateur, un flux de travail matériel de l'opérateur, ou sa configuration, et ne montre pas au relecteur comment l'inspecter.

• Captures d'écran ou courtes vidéos : placez la preuve visuelle dans sa propre section ## Visual evidence. Incluez des captures d'écran pour un écran modifié ou de courtes vidéos pour une interaction modifiée ou un flux en plusieurs étapes. Intégrez le média ou liez vers une pièce jointe stable de la PR. Les légendes doivent dire ce qui a changé et ce que le relecteur regarde. Ne substituez pas une capture d'écran du code source, un rapport de test ou un écran non modifié. Placez la preuve téléphonique avant la preuve d'ordinateur portable pour les surfaces publiques et événementielles, et identifiez chaque fenêtre d'affichage et état testé. Suivez la compétence visual-proof pour la capture, le téléchargement et la vérification du dernier commit. Omettez cette section uniquement lorsque la PR n'a aucune surface visuelle ou interactive.
• Configuration, environnement et migrations : placez uniquement les variables d'environnement, secrets, paramètres de tableau de bord et migrations de base de données réellement ajoutés, supprimés, renommés ou modifiant le comportement dans ## Configuration. Commencez par l'action unique qu'un opérateur doit entreprendre ; gardez la configuration externe ordinaire en une courte phrase, par exemple : Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes. Ne gonflez pas la section avec des détails de sondage, des justifications déjà expliquées ailleurs ou des liens vers des manuels dupliqués. Pour chaque migration réelle, nommez son chemin supabase/migrations/ validé, résumez le changement de schéma/données/politique, indiquez la compatibilité ou les exigences de rattrapage, et donnez le résultat de rejeu confirmé de npm run db:verify. Ne divulguez jamais les valeurs secrètes. Omettez la section lorsqu'il n'y a aucun changement de configuration ou de migration.
• Flux modifiés : utilisez des organigrammes Mermaid pour les flux matériels qui changent. Un flux est matériel lorsqu'il comporte plusieurs étapes, des branches, des tentatives, un transfert entre systèmes ou un chemin d'échec. Montrez le chemin modifié et son comportement d'échec important, en utilisant des étiquettes simples qu'un relecteur peut lire. Ajoutez un diagramme pour chaque flux modifié distinct. N'utilisez pas de diagramme pour un renommage en une étape ou un calcul local trivial.

Ces éléments sont séparés de l'explication principale. L'explication dit pourquoi le changement existe ; les preuves, la configuration et les diagrammes permettent à un relecteur de l'inspecter.

Gardez-le lisible

• Par défaut, 250 mots ou moins. Une description peut être plus longue lorsque l'opérateur a besoin d'une courte liste de contrôle, mais chaque phrase doit mériter sa place.
• Utilisez des paragraphes courts. Utilisez des puces uniquement pour une vraie liste, comme les étapes de configuration restantes. Ne transformez pas chaque phrase en une puce étiquetée.
• Mettez le problème, le pourquoi et le nouveau statut en anglais normal. Dites qui fait quoi.
• Évitez le code brut, les requêtes, les fragments de configuration, les codes d'état en tant que noms, le jargon, les métaphores, le battage médiatique et les tirets cadratins.
• N'expliquez pas chaque mécanisme. Gardez le comportement dont le relecteur a besoin.
• Ne répétez pas un fait dans une section ultérieure. Si une phrase peut disparaître sans perdre d'informations, supprimez-la.

Status est géré par le moniteur

Les contributeurs possèdent chaque partie de la description de PR sauf ## Status. Ne l'ajoutez pas, ne la supprimez pas et ne la modifiez pas vous-même. Le moniteur de PR BuildPurdue en est propriétaire et la maintient alignée avec l'état actuel de la révision.

Lorsqu'il modifie Status, le moniteur publie également un commentaire de PR Status update : correspondant. Il utilise une phrase en anglais simple : une prochaine action concrète avant fusion lorsqu'il reste du travail, ou No more remaining work. lorsqu'il ne reste rien. Status n'appartient jamais à un commentaire de révision de description destiné au contributeur.

N'utilisez pas Status pour des idées futures optionnelles, des notes historiques, du travail uniquement post-fusion ou du travail suivi séparément qui ne bloque pas cette PR.

Quand une structure supplémentaire est justifiée

Ajoutez une section ciblée uniquement lorsqu'elle contient des informations qui ne cadrent pas dans l'explication principale :

• Base de données / migrations : ce qui doit s'exécuter, si les données existantes restent compatibles et si un rattrapage est nécessaire.
• Comportement opérationnel : ce qui s'exécute, quand il s'exécute, comment les défaillances sont visibles et ce qu'un opérateur doit configurer.
• Vérification : vérifications manuelles confirmées et vérifications véritablement post-fusion.
• Appels ouverts : choix non résolus concernant le produit ou le risque.

Un petit correctif de bug peut simplement utiliser :

## Root cause

## Fix

## Verification

Avant de publier

1. Vérifiez que chaque affirmation provient du diff actuel, des tests, de l'état de la PR ou d'une commande que vous avez exécutée.
2. Lisez le premier écran seul. Il doit clairement indiquer le problème, pourquoi le changement était nécessaire et le nouveau statu quo.
3. Supprimez la narration historique, les journaux d'implémentation de style changelog, les explications répétées et le travail sans rapport.
4. Confirmez que toute migration, déploiement, secret, tableau de bord ou action post-fusion est explicite et exploitable.
5. Relisez-le à voix haute. Il doit ressembler à une personne qui explique le changement à un coéquipier, pas à un rapport d'audit.
6. À chaque push, comparez le corps avec le nouveau diff et mettez-le à jour lorsque le comportement, la configuration restante ou l'état de vérification a changé.

Source

Modifiez cette copie sous .agents/skills/. Le hook de pré-commit la reflète dans .claude/skills/pr-description/ ; ne modifiez pas le miroir directement.