doc / labels et décorations
Labels et décorations
Treize labels, trois décorations intégrées et cinq règles de priorité déterminent comment interpréter un commentaire — notamment s'il doit bloquer une fusion. Cette page en constitue la référence.
La syntaxe d'un commentaire
Tout commentaire soumis à validation commence par une ligne de préfixe. Après la première ligne vide vient la discussion. Son contenu est entièrement libre et n'est jamais analysé.
label [décorations]: sujet [discussion]
Dans une phrase française, on écrit normalement une espace avant les deux-points : « plateformes : ». La syntaxe Conventional Comments est différente : le deux-points fait partie de la grammaire et doit suivre immédiatement le préfixe. issue: sujet est valide. issue : sujet ne l'est pas. Pour la même raison, les noms des labels restent en anglais dans toutes les langues : ce sont des mots-clés de la syntaxe, pas du texte à traduire.
Une erreur de casse n'entraîne pas un rejet. Par exemple, Issue: déclenche W-CASE, un simple avertissement accompagné d'une correction automatique.
Les treize labels
Dix labels sont activés par défaut. Trois autres — typo, polish et quibble — sont disponibles mais désactivés initialement. Ils permettent d'affiner respectivement todo, suggestion et nitpick, et chaque dépôt peut les activer s'il en a l'usage.
| Label | Signification | Bloquant | Raccourci |
|---|---|---|---|
| 🎉 praise | Met en valeur quelque chose de particulièrement réussi. | Selon la décoration | ?pr |
| 🔍 nitpick | Signale une préférence mineure, sans véritable enjeu. | Jamais | ?ni |
| 💡 suggestion | Propose une amélioration argumentée. | Selon la décoration | ?su |
| 🔨 issue | Signale un problème identifié. Idéalement accompagné d'une suggestion. | Par défaut | ?i · ?ib |
| 📌 todo | Demande un changement limité mais nécessaire. | Par défaut | ?to |
| ❓ question | Demande une clarification sur un point incertain. | Selon la décoration | ?que |
| 💭 thought | Partage une idée apparue pendant la revue, sans demander d'action. | Jamais | ?th |
| 🧹 chore | Signale une tâche annexe à réaliser avant l'acceptation. | Par défaut | ?ch |
| 📝 note | Apporte une information utile à connaître. | Jamais | ?no |
| 🏁 decision | Acte le choix de ne pas traiter un point et en explique la raison. | Jamais | ?de |
| 🔤 typo | Signale une faute de frappe. | Désactivé par défaut | ?ty |
| ✨ polish | Propose une amélioration de finition. | Désactivé par défaut | ?po |
| 🪶 quibble | Soulève un détail discutable. | Désactivé par défaut | ?qui |
Les couleurs et les icônes sont purement visuelles et ne font pas partie du plancher d'entreprise. Les modifier ne peut donc ni changer un verdict ni faire l'objet d'une règle imposée par un administrateur.
decision — le label ajouté par ce toolkit
decision ne fait pas partie de la spécification Conventional Comments d'origine. Le toolkit l'ajoute parce que le mode enforce a besoin d'un mécanisme contrôlé pour résoudre les situations exceptionnelles. Sans cela, un fil bloquant pourrait rester ouvert indéfiniment simplement parce que son auteur n'est plus disponible.
Le seul label détecté dans une réponse non soumise à validation
Par défaut, les réponses à un fil ne sont pas validées (validateReplies: false). Une réponse dont le label résolu est decision est néanmoins reconnue. Sans cette exception, ce mécanisme ne fonctionnerait que dans les dépôts ayant déjà choisi de valider toutes les réponses.
E-DECISION-SUBJECT est une erreur, pas un avertissement
Une réponse decision doit respecter minDecisionSubjectLength, fixé à 20 caractères par défaut. C'est le seul seuil de longueur appliqué au sujet d'une decision. Résoudre un fil bloquant exige donc une véritable explication. wontfix ne suffit pas.
decision: hors périmètre pour cette PR, dette suivie en PROJ-142 Décidé avec l'équipe plateforme le 3 septembre : la réécriture du cache arrive au T4 et ce handler disparaîtra avec elle.
Tout le monde n'est pas autorisé à enregistrer une decision. resolverOverrideGroup désigne le groupe dont les membres peuvent passer outre une résolution. Ce groupe doit être configuré avant d'activer enforce ; lorsqu'il est vide, les deux mécanismes de déblocage sont indisponibles.
Décorations
Une décoration précise l'intention associée à un label. Trois décorations intégrées peuvent modifier le caractère bloquant du commentaire. Les décorations personnalisées sont également autorisées par défaut : elles peuvent apporter une information utile aux lecteurs sans jamais influencer le verdict.
| Décoration | Effet | Signification |
|---|---|---|
| blocking | Bloquant | Le point doit être résolu avant que l'objet de la revue puisse être accepté. |
| non-blocking | Non bloquant | Le point ne doit pas empêcher l'acceptation. |
| if-minor | Non bloquant | À traiter uniquement si la modification nécessaire s'avère triviale. L'auteur décide. |
| security test ux | Aucun | Décorations libres. Elles peuvent être affichées, comptabilisées et indexées, mais n'interviennent jamais dans le verdict. Chaque organisation peut définir les siennes. |
Un suggestion ou un question sans décoration déclenche W-MISSING-DECORATION. Ce sont les deux labels pour lesquels le caractère bloquant ne peut réellement pas être déduit du seul label.
Comment déterminer si un commentaire est bloquant
Cinq règles sont évaluées dans l'ordre. La première qui s'applique détermine le résultat. Il n'existe ni heuristique supplémentaire ni exception cachée.
| # | Condition | Résultat | Diagnostic |
|---|---|---|---|
| 1 | Le label est alwaysNonBlocking, mais une décoration impose le blocage. | Le comportement par défaut du label s'applique. | E-CONFLICT |
| 2 | Une décoration impose le blocage tandis qu'une autre impose le non-blocage. | Le comportement par défaut du label s'applique. | E-CONFLICT |
| 3 | Une décoration impose le blocage. | Bloquant | — |
| 4 | Une décoration impose le non-blocage. | Non bloquant | — |
| 5 | Aucune décoration n'impose de résultat. | La valeur blockingByDefault du label s'applique. | — |
Les deux premières règles signalent une erreur, mais elles produisent malgré tout un résultat. Lorsqu'un commentaire se contredit, le comportement par défaut du label sert de valeur de repli déterministe. Laisser l'état bloquant indéfini serait pire : le système ne pourrait plus déterminer si le fil empêche l'acceptation, et la pull request pourrait rester bloquée sans qu'aucune action claire permette de résoudre la situation.
Diagnostics
La validation définit quinze diagnostics. Une erreur rend le commentaire non conforme. Elle n'a d'effet sur la possibilité de fusionner que si le dépôt configure formatSeverity: "error". Un avertissement est affiché et comptabilisé, mais ne provoque jamais d'échec à lui seul. Chaque diagnostic peut changer de sévérité — ou être entièrement désactivé — dépôt par dépôt avec severities.
| Diagnostic | Déclenché lorsque |
|---|---|
| E-NO-LABEL | Le commentaire ne contient aucune ligne de préfixe. |
| E-MALFORMED-PREFIX | Le préfixe ressemble à une syntaxe valide, mais ne peut pas être analysé. |
| E-UNKNOWN-LABEL | Le label n'est pas activé pour ce dépôt. |
| E-EMPTY-SUBJECT | Le label et les deux-points sont présents, mais le sujet est vide. |
| E-DECORATION-SYNTAX | Les parenthèses ou les séparateurs des décorations sont incorrects. |
| E-UNKNOWN-DECORATION | La décoration est inconnue alors que les décorations libres sont désactivées. |
| E-CONFLICT | La règle de priorité 1 ou 2 s'applique. |
| E-DECISION-SUBJECT | Une decision n'explique pas suffisamment la décision prise. |
| Diagnostic | Déclenché lorsque |
|---|---|
| W-CASE | Le label utilise une casse incorrecte. Une correction automatique est proposée. |
| W-DECORATION-STYLE | L'espacement ou l'ordre des décorations n'est pas conforme. Une correction automatique est proposée. |
| W-SUBJECT-TOO-SHORT | Le sujet contient moins de 5 caractères. |
| W-SUBJECT-TOO-LONG | Le sujet dépasse 120 caractères. |
| W-MISSING-DECORATION | Un suggestion ou un question ne contient aucune décoration. |
| W-NO-DISCUSSION | Un commentaire bloquant ne contient aucune discussion. |
| W-NOT-BLOCKABLE | Un commentaire est déclaré bloquant dans un contexte qui ne peut pas porter cet état. |
Un sujet trop court reste un simple avertissement.
Le seuil est fixé à cinq caractères, et le franchir vers le bas ne produit jamais une erreur. Un sujet trop court n'est pas suffisamment grave pour justifier le blocage d'un workflow. Sanctionner durement les écarts mineurs pousse surtout les utilisateurs à contourner la convention plutôt qu'à l'adopter. Les contraintes fortes sont plus crédibles lorsqu'elles restent réservées aux problèmes qui le justifient réellement.