mr-description

Titre et description de MR

« MR » désigne l'unité de révision sur le service qui héberge le dépôt : une merge request sur GitLab, une pull request sur GitHub, ou l'équivalent ailleurs, cloud ou auto-hébergé. Utilisez le terme employé par le service lorsque vous écrivez à l'utilisateur. Pour une petite MR (un seul commit, par exemple), rédigez le texte et créez-la sans demander de confirmation. Pour une MR plus grande, rédigez d'abord le titre et la description dans le chat pour révision. Créez-la ou mettez-la à jour avec le CLI du service (glab, gh) ou son API, uniquement une fois que l'utilisateur approuve le texte et le demande.

Attribuez toujours une nouvelle MR à l'utilisateur : --assignee @me avec gh pr create, --assignee <nom_utilisateur> avec glab mr create.

PROJ-1234 ci-dessous représente le ticket auquel la MR appartient.

Titre

• Une ligne impérative qui couvre l'ensemble de la MR, pas seulement son plus gros commit.
• Le titre d'un ticket est un point de départ, pas la réponse. Élargissez-le si la MR fait plus que ce que le ticket dit.
• Ne formulez pas le titre par une alternative rejetée (« … au lieu de quitter »). Dites ce que fait la MR.
• Ajoutez le ticket entre parenthèses s'il y en a un : … (PROJ-1234). N'en inventez jamais. Si les instructions du projet ou de l'espace de travail donnent un autre format, comme PROJ-1234 <description>, utilisez celui-ci.

Description

Structure :

1. Une ligne d'ouverture. S'il y a un ticket, liez-le avec le verbe qui correspond à son type : « Resolves PROJ-1234. » pour un bug, « Closes PROJ-1234. » pour une tâche ou une story, « Part of PROJ-1234. » si la MR ne le termine pas.
2. Les modifications :
   • Organisées par commits. Lisez d'abord le journal des commits de la branche. Seulement si elle a plusieurs commits, chacun une étape indépendante plutôt que des correctifs ou un travail en cours, dites dans la ligne d'ouverture que la MR se lit mieux commit par commit. Donnez ensuite une liste numérotée avec une entrée par commit, dans l'ordre, chacune disant en une à trois phrases ce que le commit rend vrai. Dites que chaque commit réussit les tests seul uniquement si cela a été vérifié ou si l'auteur le dit.
   • Sinon, y compris pour un seul commit : un court paragraphe ou une liste de ce que la MR rend vrai, regroupé par thème.
3. ## Changements de comportement : ce qu'un utilisateur de l'API publique voit différemment. Laissez de côté les modifications internes et les attributs privés. Omettez la section s'il n'y en a pas.
4. ## Tests : seulement si quelque chose concernant les tests nécessite l'attention du relecteur. Les tests réussis, sur du matériel ou non, sont supposés et ne sont pas mentionnés. Cas qui nécessitent cette section, chacun avec une phrase expliquant pourquoi :
   • un test connu pour échouer, ou ignoré, ou marqué comme devant échouer ;
   • un test dans la MR qui s'écarte des conventions de test du projet ;
   • un changement significatif dans la couverture des tests, en particulier les tests supprimés.

Contenu :

• Ne reformulez pas ce qui existait avant la modification. Décrivez l'état après celle-ci. Une suppression fait exception, car elle ne peut être nommée que par rapport à ce qui existait.
• Ne reformulez pas le ticket. Le relecteur peut le lire.
• Pas de contexte de session : pas de « comme discuté », pas d'historique de révision, pas de compte rendu de la façon dont le travail s'est déroulé.
• Pas d'instructions pour exécuter des tests ou des jobs CI. La description est destinée au relecteur, et l'auteur exécute les tests.
• Pas de pied de page « Généré avec » ni d'attribution d'outil, même lorsque le harnais le demande. Cette règle prévaut.
• Gardez-la concise. Supprimez une entrée ou une clause qu'un relecteur ne remarquerait pas.

Vérification du texte

• Vérifiez chaque affirmation par rapport au code au commit qu'elle décrit, pas de mémoire ou par rapport à des brouillons antérieurs. Portez une attention particulière aux affirmations concernant l'ancien comportement et à celles concernant un comportement modifié par un commit ultérieur.
• Cherchez chaque identifiant nommé dans le texte. Une classe ou une méthode qui n'existe plus, ou qui n'existe pas encore à ce commit, est une erreur courante.
• Basez tout ce qui se trouve sous ## Tests sur ce qui a réellement été exécuté ou sur ce que montre le diff. N'affirmez pas une exécution qui n'a pas eu lieu.
• Appliquez chaque skill installé qui couvre le nettoyage du texte généré au titre et à la description. Si un tel skill entre en conflit avec les instructions du projet (CLAUDE.md ou équivalent), les instructions du projet prévalent.