From ef3df2d9397ab09a294da18edd4e62a32c41eb25 Mon Sep 17 00:00:00 2001 From: NotExpectedYet Date: Sun, 27 Sep 2026 07:05:43 +0100 Subject: [PATCH] docs: commit each step as the work lands, not in one lump at the end The subjects are the release notes, so a working tree is a queue of unwritten sentences: a change left uncommitted until the end is a change with no note, and a batch of unrelated changes cannot be split into honest subjects once the reasoning behind each one is only in the transcript. The second reason is the one that changes a version, so it is stated too: the range picks its bump from whatever subjects it ends up with, and one `feat:` batched in with a handful of fixes is a minor bump for all of them. Also says outright that committing is local, because pushing to `master` is what releases and that is a different decision. --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0e50364..ab38f70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,24 @@ release notes. Write it for that reader: `feat` has to be a word, so `Fix the feature flag leak` is a patch. Only the subject line is read; the body is not. +## Commit as the work lands + +Commit each step as soon as it is finished rather than leaving it in the tree +until the end. Two reasons, and the second is the one that bites: + +- An uncommitted change has no release note at all. The subject is the sentence a + user reads, so work that never becomes a commit never becomes a sentence. +- A tree carrying four unrelated changes cannot be split into four honest + subjects after the fact — the reasoning behind each one is only in the + transcript by then, and the range picks its bump from whatever subjects it + ends up with. One `feat:` batched in with a handful of fixes is a minor bump + for all of them. + +Keep a subject to one change and the version follows from it. + +A commit here is local. Pushing to `master` is what releases, so it stays a +separate, deliberate step. + ## The release job owns the version and the changelog `package.json`'s `version` and `CHANGELOG.md` are the job's to write, derived