From e4d3faed6af66f095198c8ebd80fc940e7660429 Mon Sep 17 00:00:00 2001 From: Lucas Winther Date: Wed, 14 Oct 2026 17:49:38 +0200 Subject: [PATCH] docs: the number of commits is never the thing to minimise The owner's rule, recorded so the next agent does not squash a multi-part fix to keep the changelog to one line: one coherent change per commit, each passing alone, ordered so each is safe to ship alone, with a single changelog entry naming the range. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ea4a082..b64f3b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1150,6 +1150,13 @@ to an open page). Four things hold it up: that says *why* — the reasoning a diff cannot show — rather than listing the files it touched. Never reformat code the change did not touch; a formatter the project does not run buries a 100-line change in a 550-line diff. + **The number of commits is never the thing to minimise** (repository owner, 2026-10-14). A fix that + is really four changes — a client migration, a parser fix, a merge rule, a feed field — is four + commits, each one reading on its own and passing on its own. Do not squash them to keep the + changelog to one line: a change spanning several commits gets one entry naming the range, as the + bullet below already allows, so the changelog's length is not an argument about the history. + Order them so every one is safe to ship alone — a migration that protects readers' keys lands + *before* the change that moves the keys. - **A change a reader can see adds a changelog entry** (`src/shared/changelog.ts`, PRD F18): one reader-facing line, its kind, its date and the commit it shipped in. A commit cannot contain its own hash, so the entry lands in a follow-up `chore(changelog)` commit naming the one before it. A