Standards des messages de commit Git et métadonnées

Résumé exécutif

Bienvenue dans la référence d'ingénierie définitive pour le formatage, la structuration et la préservation des métadonnées dans les messages de commit Git. Ce document encapsule les conventions essentielles pour l'hygiène des commits, qui sont indispensables pour maintenir des historiques de logs propres, lisibles et hautement traçables tout au long des cycles de développement.

L'adhésion à ces standards assure la traçabilité des métadonnées et fournit un contexte clair et durable aux futurs développeurs.

Résumé

Chapitre : Conventions de titre de commit

Contexte : La ligne de titre d'un message de commit Git est la première ligne de retours visuels pour les ingénieurs naviguant les logs du repository. Pour assurer un dimensionnement standard, la clarté et la lisibilité, les structures de titre sont soumises à des contraintes rigides.

Résumé

Règles

T1-01 : Titres de commit concis et impératifs

Règle : Les titres de commit doivent être de 60 caractères ou moins, commencer par un verbe impératif (par ex. « Add », « Fix », « Update », « Remove »), et utiliser la casse de phrase sans ponctuation finale.

Quoi : La ligne de titre du commit doit être un résumé concis et impératif strictement limité à 60 caractères ou moins.

S'applique à : Première ligne du message de commit Git.

Pourquoi : Les règles de validation essentielles de la base de code bloquent et signalent programmatiquement les commits avec des sujets dépassant 60 caractères. Garder le titre sous cette limite stricte évite les blocages de téléchargement du repository et assure un affichage net dans les outils CLI.

Piège 1 : Écrire des titres passifs, trop longs ou descriptifs avec des verbes progressifs ou au passé.

Ne pas faire :

Fixing the loading spinner bug in gr-reply-dialog.ts and adding tests

Faire :

Fix loading spinner and add test coverage

Chapitre : Structure et formatage du corps du commit

Contexte : Le corps d'un commit est un actif vital du repository stockant l'intention architecturale derrière une modification. Il doit expliquer les décisions d'ingénierie avec concision pragmatique, fournir un contexte ciblé et être enveloppé strictement pour la compatibilité terminale.

Résumé

Règles

T2-01 : Expliquer le contexte : quoi et pourquoi

Règle : Le corps du message de commit doit clairement expliquer quelles modifications ont été apportées et pourquoi elles étaient nécessaires, en se concentrant sur le contexte et l'intention architecturale, tout en maintenant un ton concis, non redondant et pragmatique. Le corps doit sauter directement au contexte technique ou au problème et ne doit jamais répéter, reformuler ou commencer par un résumé introductif de haut niveau du titre. Pour les modifications complexes, sensibles à la sécurité ou à risque élevé, l'explication doit explicitement justifier le « pourquoi » en référençant l'enjeu pertinent, l'ID de suivi de bug ou le document de conception/RFC. N'incluez pas de références de bug vides, de faible valeur ou vagues (par ex. « To address b/XXXXX, ... ») dans le texte du corps, sauf si accompagnées d'un contexte descriptif expliquant ce que représente le bug ou l'enjeu. Si le contexte de bug spécifique n'est pas connu ou ne peut pas être vérifié, la référence de bug doit être complètement omise des paragraphes du corps, en s'appuyant uniquement sur le pied de page de métadonnées pour le suivi.

Quoi : Les explications du corps doivent détailler le problème et la justification de la solution, laissant le « comment » mécanique à lire dans la diff du code, et omettant les propositions de valeur génériques des pratiques de développement, les remplissages non techniques ou les phrases méta-introductives. Le paragraphe d'ouverture du corps doit commencer directement par le contexte ou le problème résolu et ne pas rénoncer ou reformuler le titre du commit. Si le commit est lié à un problème complexe ou implémente une spécification de conception approuvée, le corps doit s'appuyer sur ces ressources liées et les citer pour clarifier le raisonnement de manière directe et claire. Si vous citez un ID de suivi de bug dans les paragraphes du corps, assurez-vous qu'il ajoute une valeur concrète en décrivant quel problème ou retour est suivi là ; sinon, laissez la référence de bug hors de la narration du corps et laissez le pied de page gérer le lien.

S'applique à : Lignes du message de commit suivant la ligne vide d'espacement (ligne 3 et au-delà).

Pourquoi : Les listes de code évidentes sont redondantes. Le contexte est clé : pour les modifications d'ingénierie complexes ou sensibles, les mainteneurs ultérieurs doivent comprendre l'origine d'une exigence ou d'une contrainte de conception (par ex. un bug spécifique, une CVE ou une spécification de conception) sans devoir deviner, établissant une traçabilité claire.

Piège 1 : Répéter ou reformuler le titre, commencer le corps par une phrase de résumé introductive de haut niveau, ou omettre le contexte concret.

Le titre du commit est déjà le résumé de haut niveau de la modification. Commencer le corps du message de commit par une reformulation, un énoncé ou une « thèse introductive » (par ex. « Add the agent and define its corresponding guidelines ») est hautement redondant et gaspille le temps du lecteur. N'écrivez pas de phrases méta-introductives ; commencez les paragraphes du corps en sautant directement au contexte technique ou au problème résolu.

Ne pas faire :

Fix loading spinner and add test coverage

This change fixes the loading spinner and adds test coverage to gr-reply-dialog.ts.

(Problème : Répète presque mot pour mot le titre dans l'ouverture du corps.)

Faire :

Fix loading spinner and add test coverage

The loading spinner in gr-reply-dialog was experiencing visual jitter
on rapid page transitions due to a race condition in the reactive
lifecycle hook.

This change moves property assignments out of firstUpdated to avoid
unnecessary second-pass rendering, stabilizing the visual state.

(Justification : Saute directement au problème concret.)

Piège 2 : Omettre le contexte des bugs liés ou des documents de conception dans les modifications complexes, critiques ou sensibles à la sécurité.

Bien que les corrections de bugs simples ou mineures n'aient pas besoin de référencer explicitement leurs ID d'enjeu dans le corps, les modifications majeures, à haut risque ou architecturales qui référencent des spécifications externes, des RFC ou des tickets de suivi de bug doivent intégrer ce contexte dans l'explication du « pourquoi ». Ne pas le faire rend le message de commit déconnecté de ses métadonnées, rendant la révision et l'auditabilité difficiles.

Ne pas faire :

Enhance project deletion permission validation

Only users with administrative privileges are allowed to delete a
project, but the server was previously checking for owner status only.
This change corrects the check to require system administrator scope.

Bug: gerrit:40012901

(Problème : Une modification sensible du modèle de permission est apportée en vertu d'un bug, mais le corps explique uniquement la modification mécanique. Il omet complètement le contexte de sécurité—comme le contournement de permission mentionné dans le rapport de bug—rendant le raisonnement de cette modification à risque élevé peu clair sans consulter le bug.)

Faire :

Enhance project deletion permission validation

To resolve the permission bypass reported in gerrit:40012901, where
project owners could bypass global security policies to delete resource
containers, we must restrict deletion calls to administrators.

As defined in the project deletion security spec (https://example.com/gerrit-delete-spec),
only system-level administrators should have the capability to
destroy project repositories in production environments.

Bug: gerrit:40012901

Piège 3 : Ajouter des références de bug/enjeu vagues ou de faible valeur au corps du commit.

N'introduisez pas de phrases ou de phrases génériques, remplisseuses (comme « To address b/12345... », « In reference to b/12345... » ou « As requested in b/12345... ») dans la narration du corps d'un message de commit, sauf si vous ajoutez réellement un contexte descriptif et précieux provenant de ce bug ou document de conception. Si le contexte du bug n'est pas connu, ou si vous ne pouvez pas visiter/vérifier le contenu du bug, omettez la référence du texte du corps entièrement. Le pied de page de métadonnées au bas (par ex. Bug: b/12345 ou Google-Bug-ID: b/12345) est le bon endroit pour gérer le suivi automatisé ; ajouter une mention vague au corps n'ajoute aucune valeur explicative et n'augmente que le bruit.

Ne pas faire (Référence vague dans le corps) :

Suggest full commit message and avoid pedantic reviews

To address b/505405738, this change updates the review guidelines to
require that commit message reviews provide a complete, copy-pasteable
revised message when formatting issues are found. It also instructs the
reviewer to avoid pedantic feedback on minor casing or phrasing if the
original message is already clear and compliant.

Google-Bug-ID: b/505405738
Release-Notes: skip
Change-Id: I75ef56099ea36b8838a65746abb3a4771fcefd23

(Problème : Le paragraphe du corps commence par « To address b/505405738, ... », mais cette phrase n'explique pas ce que représente le bug ou quel contexte il fournit. C'est une phrase de remplissage mécanique de faible valeur.)

Faire (Quand le contexte du bug est inconnu - omettre la référence du corps) :

Suggest full commit message and avoid pedantic reviews

Automated commit message reviews can sometimes generate fragmented,
pedantic feedback on minor phrasing nits, creating friction rather than
saving developer time.

To improve usability, SKILL.md now requires reviewers to generate a
complete, copy-pasteable revised commit message when formatting issues
are found, and to suppress feedback on minor nits if the original
commit is fundamentally sound.

Google-Bug-ID: b/505405738
Release-Notes: skip
Change-Id: I75ef56099ea36b8838a65746abb3a4771fcefd23

(Justification : Puisque le contexte du bug n'a pas été explicitement visité ou vérifié, la référence vague est complètement supprimée du texte du corps, et le corps saute directement au contexte du problème d'abord plutôt que de commencer par une déclaration générique « This change... ».)

Faire (Quand le contexte du bug est visité/connu - intégrer le contexte descriptif) :

Suggest full commit message and avoid pedantic reviews

In b/505405738, developers reported being slowed down by fragmented,
pedantic automated review feedback and requested ready-to-apply
suggestions to reduce manual editing friction.

To address this, this change updates the guidelines to require a
complete, copy-pasteable revised message when formatting issues are
found, and instructs reviewers to tolerate minor casing or phrasing
variations when the original message is already compliant.

Google-Bug-ID: b/505405738
Release-Notes: skip
Change-Id: I75ef56099ea36b8838a65746abb3a4771fcefd23

(Justification : La référence de bug dans le corps ajoute maintenant une valeur réelle en expliquant exactement quel problème/retour a été signalé dans b/505405738, fournissant un contexte important aux futurs mainteneurs, tout en expliquant le problème/besoin avant la solution.)

T2-02 : Enveloppe stricte des lignes à 72 caractères

Règle : Enveloppez le corps de tous les messages de commit strictement à 72 caractères par ligne, sauf pour les URLs non-enveloppables, les chemins de fichiers ou les commandes.

Quoi : Les lignes du corps du commit doivent avoir des retours à la ligne explicites à ou avant 72 colonnes.

S'applique à : Corps des messages de commit Git.

Pourquoi : Les écrans de sortie terminale s'enveloppent à des colonnes standard. L'enveloppe explicite à 72 caractères assure une lecture propre dans les éditeurs de texte simples, les visionneuses CLI et les visionneuses de patch.

Piège 1 : Ajouter des paragraphes complets sans enveloppe manuelle des mots.

Ne pas faire :

This change refactors the core caching helper and resolves a race condition that occurs when the same component gets disconnected rapidly from the DOM during teardown, which historically resulted in an uncaught exception.

Faire :

This change refactors the core caching helper and resolves a race
condition that occurs when the same component gets disconnected
rapidly from the DOM during teardown, which historically resulted
in an uncaught exception.

T2-03 : Ton pragmatique, concision et anti-remplissage

Règle : Les messages de commit doivent être concis, directs et libres de remplissage conversationnel, de généralités évidentes, de discours marketing/relations publiques ou de structure passe-partout excessif. Chaque phrase doit servir à communiquer le contexte technique.

Quoi : Évitez les introductions longues (par ex. « To ensure standard high-quality... »), les poncifs (par ex. « Commit messages are vital repositories of engineering intent... ») et les modèles rigides de style Q&A (comme les en-têtes « What is changing / Why this is necessary ») sauf si la modification est hautement complexe et structurellement les demande. Gardez les explications simples, directes et concentrées sur le problème technique et sa solution.

S'applique à : Corps des messages de commit Git.

Pourquoi : Les messages de commit verbeux, fleuris ou hautement modélisés encombrent les logs du repository et augmentent la charge cognitive pour les ingénieurs recherchant l'historique. Le temps d'un chef d'équipe est précieux ; le message de commit doit fournir le ratio signal-sur-bruit maximum.

Piège 1 : Inclure des justifications génériques d'ingénierie logicielle ou expliquer pourquoi l'examen du code, les tests ou les bonnes pratiques sont importants en général. N'écrivez pas d'essais sur la philosophie générale de conception dans le message de commit. Tenez-vous strictement aux faits techniques spécifiques de la modification.

Ne pas faire :

Register gerrit-commit-message-review agent and skill

To enforce rigorous commit log hygiene across this repository, this
change registers the new 'gerrit-commit-message-review' AI reviewer
agent and establishes its associated quality guidelines.

Commit messages are permanent repositories of engineering intent, but
manual review is prone to human oversight. Under the feature request
in Issue 505405738, this system automates audit checks to provide
instant, high-fidelity feedback. By deploying a specialized agent that
evaluates formatting style, structural completeness, and footer
integrity, developers receive automated proofreading findings directly
in the Gerrit Checks UI (with ready-to-apply autofixes where
applicable).

(Problème : Texte hautement verbeux et générique expliquant les propositions de valeur générales de l'examinateur IA et l'hygiène du repository, rempli de phrases d'remplissage comme « Commit messages are permanent repositories... »)

Faire :

Register gerrit-commit-message-review agent and skill

To automate commit log hygiene audits across this repository, this
change registers the new agent to trigger automatically on COMMIT_MSG
changes. The accompanying skill definition outlines rules for
subject-line format, strict 72-character line wrapping, context and
intent explanation, and strict preservation of integration footers.

Bug: Issue 505405738

(Justification : Ratio signal-sur-bruit élevé. Évite complètement les références d'enjeu vagues du corps et saute directement au mécanisme technique, laissant la liaison d'enjeu au pied de page de métadonnées.)

Piège 2 : Forcer les dispositions multi-sections complexes (comme les points de liste ou les en-têtes Q&A) pour les modifications simples, de taille moyenne ou droites. Utilisez des paragraphes simples et directs au lieu de listes et d'en-têtes structurels chaque fois que possible. N'utilisez les listes numérotées que pour énumérer une séquence de modifications architecturales très distinctes.

Ne pas faire :

Fix loading spinner and add test coverage

What is changing:
1. The loading spinner in gr-reply-dialog.ts is fixed.
2. Property assignments are moved out of firstUpdated to avoid dual rendering.
3. Tests are added.

Why this is necessary:
The loading spinner was experiencing visual jitter on rapid page transitions
due to a race condition in the reactive lifecycle hook, which is bad for UX.

(Problème : Une correction de bug triviale est forcée dans une structure multi-têtes avec des formulations redondantes.)

Faire :

Fix loading spinner and add test coverage

The loading spinner in gr-reply-dialog was experiencing visual jitter
on rapid page transitions due to a race condition in the reactive
lifecycle hook.

This change moves property assignments out of firstUpdated to avoid
unnecessary second-pass rendering, stabilizing the visual state.

(Justification : Court, élégant, deux paragraphes de flux narratif. Explique entièrement le problème et la solution de haut niveau sans surcharge structurelle rigide et répétitive.)

Piège 3 : Sur-expliquer les modifications simples, utiliser des narrations séquentielles (« First », « Second »), ou expliquer les avantages évidents de l'expérience développeur. Évitez d'écrire plusieurs paragraphes ou listes séquentielles pour expliquer les améliorations simples et singulières. Ne consacrez jamais de phrases à expliquer pourquoi une modification est bénéfique en général (par ex. expliquer que « this saves developer effort » ou « improves developer experience »). Fondez l'explication uniquement sur le delta technique et gardez les modifications simples dans un seul paragraphe dense de 2 à 3 phrases maximum.

Ne pas faire (Trop verbeux) :

Suggest full commit message and avoid pedantic reviews

To address b/505405738 and improve the developer experience when
addressing commit message feedback, this change updates the review
guidelines in SKILL.md with a new chapter outlining response standards.

First, if any formatting or hygiene issues are found, the reviewer must
provide a complete, fully-compliant, and copy-pasteable revised commit
message. This saves developer effort and streamlines the edit workflow.

Second, to prevent automated review noise, the reviewer must adopt a
pragmatic approach and tolerate minor casing or subjective phrasing
differences if the message is already clear and compliant.

(Problème : Hautement verbeux, utilise l'énumération séquentielle (« First », « Second »), et explique les avantages génériques évidents comme « This saves developer effort and streamlines the edit workflow ».)

Faire (Ultra-concis et haute densité) :

Suggest full commit message and avoid pedantic reviews

Automated commit message reviews can generate fragmented, pedantic
feedback on minor phrasing nits, creating friction rather than saving
developer time. This change updates SKILL.md to require reviewers to
provide a complete, copy-pasteable revised commit message when
violations are found, and to tolerate minor variations if the original
message is fundamentally compliant.

Google-Bug-ID: b/505405738
Release-Notes: skip

(Justification : Hautement concis et ratio signal-sur-bruit élevé. Explique d'abord le contexte du problème/pourquoi, et évite toute référence d'enjeu vague ou phrases méta-introductives « This change... », tout en utilisant le pied de page de métadonnées pour la liaison de bug.)

Chapitre : Pieds de page métadonnées et préservations

Contexte : Les pieds de page de métadonnées dynamiques servent de liens d'intégration vitaux reliant les modifications du code aux systèmes de suivi d'enjeux, aux plateformes d'examen de code et aux pipelines automatisés d'audit de publication.

Résumé

Règles

T3-01 : Préservation obligatoire du pied de page d'intégration

Règle : Conservez toujours tous les pieds de page de métadonnées git structurés au bas du message de commit, correspondant au style de suivi approprié en fonction du contexte de l'environnement.

Quoi : Ne modifiez pas, ne corrompez pas et ne supprimez pas les pieds de page critiques du système tels que Change-Id, Bug ou les clés de suivi du tracker pendant les modifications.

S'applique à : Bloc de pied de page du message de commit au bas.

Pourquoi : Les plateformes d'examen de code (telles que Gerrit) suivent strictement les révisions en utilisant le pied de page Change-Id. Le supprimer détache l'historique de révision ou brise les webhooks d'intégration. De même, les systèmes de suivi d'enjeux s'appuient sur les clés correspondantes (par ex. Bug: <ID>, Closes #<ID>) pour lier les commits de code avec les tickets du projet.

Piège 1 : Modifier ou réécrire le message de commit et supprimer les pieds de page de métadonnées d'origine.

Ne pas faire :

Update system cache configs

Refactored memory size and cache duration parameters.

Faire (Format standard du suivi d'enjeux) :

Update system cache configs

Refactored memory size and cache duration parameters.

Bug: Issue 12345
Release-Notes: skip
Change-Id: Iab12cd34ef560078009000120034005600780090

Faire (Format du suivi GitHub/GitLab) :

Update system cache configs

Refactored memory size and cache duration parameters.

Closes #1234567
Release-Notes: skip
Change-Id: Iab12cd34ef560078009000120034005600780090

Chapitre : Retours de révision et message de commit suggéré

Contexte : Pour fournir une valeur maximale et minimiser les frictions, le relecteur ne doit pas seulement signaler les violations de formatage/hygiène, mais aussi fournir un message de commit complet, corrigé et entièrement conforme que le développeur peut copier et coller directement dans l'éditeur de message de commit de Gerrit.

Résumé

Règles

T4-01 : Fournir un message de commit complet suggéré

Règle : Chaque fois que des problèmes de formatage, de structure ou d'hygiène sont identifiés dans le message de commit, le retour de révision doit inclure une section dédiée contenant la version complète, entièrement conforme et améliorée du message de commit enveloppée dans un bloc de code markdown (par ex. en utilisant la coloration syntaxique text ou git). Si le message de commit d'origine est déjà satisfaisant, entièrement conforme et informatif, aucune version révisée ou suggestion ne doit être fournie.

Quoi : Le retour de révision doit fournir le message de commit révisé complet dans un seul bloc de code comme remplacement clé en main UNIQUEMENT lorsque des violations ou des améliorations potentielles sont trouvées. Ce message suggéré doit appliquer méticuleusement toutes les directives définies dans cette compétence (par ex. longueur de titre inférieure à 60 caractères, verbes impératifs, enveloppe stricte de 72 caractères dans le corps, explication pragmatique et concise). Il doit préserver tous les pieds de page de métadonnées existants (comme Change-Id, Bug, Closes et Release-Notes) exactement comme ils apparaissaient dans le message d'origine. Si le message de commit est déjà entièrement conforme, le relecteur doit déclarer qu'aucune amélioration n'est nécessaire et omettre le bloc de suggestion.

S'applique à : Rapports de retours de révision et commentaires de résumé sur COMMIT_MSG.

Pourquoi : Les développeurs veulent résoudre les problèmes de formatage aussi rapidement que possible. Fournir un message amélioré complet et directement copiable élimine le besoin pour le développeur de ré-envelopper manuellement les lignes ou de réécrire les phrases, améliorant significativement l'expérience développeur. Cependant, forcer une réécriture quand le message est déjà de haute qualité cause du bruit et des frictions inutiles.

Piège 1 : Fournir des commentaires de retour sur les lignes individuelles mais omettre un seul message de commit révisé unifié.

Ne pas faire :

Line 1: The title has 65 characters, which is over the 60-character limit. Please shorten it.
Line 3: This line is 85 characters long. Please wrap it at 72 characters.

Faire :

### Commit Message Review

I found a few formatting issues with your commit message:
1. The title is too long (65 characters).
2. The body paragraphs are not wrapped at 72 characters.

Here is an improved, fully-compliant version of your commit message that you can copy and paste directly into the Gerrit edit dialog:

```text
Fix loading spinner and add test coverage

The loading spinner in gr-reply-dialog was experiencing visual jitter
on rapid page transitions due to a race condition in the reactive
lifecycle hook.

This change moves property assignments out of firstUpdated to avoid
unnecessary second-pass rendering, stabilizing the visual state.

Bug: Issue 12345
Release-Notes: skip
Change-Id: Iab12cd34ef560078009000120034005600780090
```

(Justification : Fournit une solution prête à l'emploi qui économise l'effort du développeur.)

T4-02 : Tolérance pragmatique et anti-bruit

Règle : Le relecteur doit adopter une approche pragmatique et non pointilleuse pour évaluer les messages de commit. NE SUGGÉREZ PAS de réécritures pour les différences stylistiques mineures, les préférences de formulation subjective ou les choix de casse triviaux si le message d'origine est déjà clair, informatif, correctement enveloppé et conforme aux limites essentielles.

Quoi : Appliquez un seuil élevé de valeur avant de signaler un message de commit ou de suggérer une alternative. Les points stylistiques triviaux (tels que commencer un préfixe de composant deux-points avec un verbe minuscule, par ex. GrepServlet: add ... vs GrepServlet: Add ..., ou des structures de phrase légèrement différentes qui expriment le même contexte) sont considérés comme acceptables. Le relecteur ne doit jamais poster de commentaires ou générer un bloc de suggestion pour ces variations mineures. Suggérez des révisions uniquement quand il y a des violations claires et objectives (par ex. titre > 60 caractères, lignes du corps > 72 caractères, contexte essentiel manquant ou métadonnées corrompues/manquantes).

S'applique à : Tous les rapports de retours de révision et commentaires.

Pourquoi : Les révisions superflues ou pointilleuses (souvent appelées « bruit pointilleux ») irritent les auteurs, gaspillent les cycles de révision et érodent la confiance dans les outils automatisés. Les critiques IA doivent se concentrer strictement sur les standards de correction de haute valeur, de sécurité et de lisibilité critique.

Piège 1 : Signaler un message de commit bien écrit, informatif et correctement enveloppé sur des formatages mineurs de phrase ou de casse de préfixe.

Ne pas faire (Bruit pointilleux) :

### Commit Message Review

The title uses a lowercase verb after the prefix ("add" instead of "Add"). Also, we can improve the body phrasing to be slightly more descriptive.

Suggested Commit Message:
GrepServlet: Add JSON content search endpoint

To support content search in Gitiles (Issue 376381593)...

(Problème : Le message de commit d'origine était déjà exceptionnel. Suggérer une réécriture pour les différences triviales de casse et de formulation n'ajoute aucune valeur structurelle.)

Faire : Déclarez que le message de commit est entièrement conforme et satisfaisant, et ne posez aucun commentaire individuel ou réécriture suggérée.