From 55a093a86d13189fc1b417d932723287c0caf32a Mon Sep 17 00:00:00 2001 From: Mathieu Benoit Date: Tue, 25 Aug 2026 05:40:44 -0400 Subject: [PATCH] [ADD] convention : ce qu'un sujet de commit doit dire MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le manuel encadrait le corps en détail — pourquoi, dix lignes par langue, ce qu'on ne répète pas du diff — et ne disait du sujet que « courte, à l'impératif ». Le sujet est pourtant lu cent fois pour une fois que le corps l'est : git log --oneline, un blame, un bisect, une note de version. Faute de règle, les sujets dérivent vers le symptôme et la métaphore, qui se lisent bien sans nommer la partie du système en jeu. La règle ajoute une épreuve, pas un gabarit : lire le sujet seul, sans diff ni corps, et savoir ce qui change et où. Les trois exemples avant/après viennent de l'historique du dépôt, un exemple inventé ne convainquant personne. --- EN --- The manual framed the body in detail — why, ten lines per language, what not to repeat from the diff — and said of the subject only that it be short and imperative. Yet the subject is read a hundred times for every reading of the body: git log --oneline, a blame, a bisect, a release note. With no rule, subjects drift towards the symptom and the metaphor, which read well without naming the part of the system at stake. The rule adds a test, not a template: read the subject alone, with no diff and no body, and be able to say what changes and where. The three before/after pairs come from the repository's own history, an invented example convincing nobody. Assisted-by: Claude Opus 5 (cherry picked from commit c86357eab899c65f41287d4f19e88d0da98285c4) --- .claude/rules/04-code-conventions.md | 20 +++++++++++++++ conf/template_claude_commands_commit.md | 33 +++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/.claude/rules/04-code-conventions.md b/.claude/rules/04-code-conventions.md index 4001c2f..75e1616 100644 --- a/.claude/rules/04-code-conventions.md +++ b/.claude/rules/04-code-conventions.md @@ -16,6 +16,26 @@ indentations par type de fichier. caractères au plus. Tags réellement utilisés : `[UPD]`, `[FIX]`, `[ADD]`, `[IMP]`, `[REF]`. +### Le sujet + +Le sujet est lu cent fois pour une fois que le corps l'est — `git log +--oneline`, un blame, une note de version, un bisect. Il a une seule tâche : +dire **sur quoi porte le code**. + +L'épreuve : le lire seul, sans diff ni corps. Sait-on quelle partie du système +est en jeu, et ce qui y est désormais différent ? Sinon il n'est pas fini. + +Nommer la chose, puis ce qui change pour elle. Le symptôme, le message d'erreur +cité et la métaphore sont des PREUVES, et une preuve va dans le corps — un +sujet bâti sur elles se lit bien et n'apprend rien. La portée dit OÙ, les mots +après le deux-points doivent dire QUOI. + +Le sujet résume le commit ENTIER, pas sa plus grosse pièce. S'il lui faut un +« et » entre deux choses sans rapport, c'étaient deux commits. + +Le mode d'emploi complet, avec des exemples avant/après pris dans l'historique +de ce dépôt, est dans `conf/template_claude_commands_commit.md`. + ### Tout commit assisté par IA Trois exigences, sans exception — `AI_POLICY.md` en donne la raison : diff --git a/conf/template_claude_commands_commit.md b/conf/template_claude_commands_commit.md index e97ca07..ad00dc4 100644 --- a/conf/template_claude_commands_commit.md +++ b/conf/template_claude_commands_commit.md @@ -90,6 +90,39 @@ The same body, translated. Assisted-by: {MODEL} ``` +### The subject line + +The subject is read a hundred times for every time the body is read: in +`git log --oneline`, in a blame, in a release note, in a bisect. It has one +job — say what the code is about. + +**The test.** Read the subject alone, with no diff and no body. Can you say +which part of the system it concerns, and what is now different about it? If +not, it is not finished. + +**Name the thing, then what changed about it.** The symptom, the quoted error +and the metaphor are EVIDENCE, and evidence belongs in the body. A subject +built on them reads well and tells the next reader nothing: + +| Instead of | Write | +|-----------|-------| +| `[FIX] nettoyage : les enfants s'en vont avec leur rebond` | `[FIX] nettoyage : les entrées ssh qui rebondissent par une VM effacée` | +| `[FIX] proxmox : « il manque le stockage » était le symptôme, pas la cause` | `[FIX] proxmox : signaler pmxcfs à terre, et non « aucun stockage »` | +| `[FIX] migration: un module fautif n'emporte plus tout le lot` | `[FIX] migration: isoler l'échec d'un module dans la désinstallation` | + +The scope is not the subject. `proxmox` says WHERE; the words after the colon +must say WHAT. A subject that works with its scope removed is usually the +right one. + +**Summarise the whole commit, not its largest piece.** When the work has two +faces — a guard moved and the check that proves it, a screen and the service +under it — the subject covers both or the commit should have been two. If the +only honest subject needs an `and` joining two unrelated things, split it. + +**It must be complete in 72 characters.** A subject cut mid-phrase by +`--oneline` has failed at the one place it is read most. Write it to fit +rather than trimming it afterwards: drop the adjectives, keep the nouns. + ### Keep it short The body answers one question: why was this necessary. Stop once it is