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.
This commit is contained in:
NotExpectedYet committed 2026-09-27 07:05:43 +01:00
1 parent ef8829cb56
commit ef3df2d939
1 file changed
+18
+18
View File
@@ -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