Caught while cutting 6.0.0, after the tag was pushed and before the publish was approved.
bun run scripts/release.ts --bump major generates a ## <version> section from commit subjects and appends it, leaving the hand-written ## [Unreleased] section untouched above it. So the tree ended up as:
## [Unreleased] <- the 7 BREAKING entries and every migration
## 6.0.0 <- commit subjects, including #238/#237/#234 which shipped in 5.0.1
wiki/Upgrading.md tells the reader "read the 6.0.0 section, in order" — and that section did not contain the migration. For a major whose entire value is its upgrade guide, that is the failure the guide exists to prevent.
It has happened before. CHANGELOG.md carried two ## 5.0.1 headings — one auto-generated from commit subjects, one hand-written — from the previous release run. Nobody noticed, which is the argument for a check rather than more care.
Also wrong in the generated section: it includes commits that shipped in an earlier release (#238, #237, #234 were 5.0.1), because the range it reads is not bounded by the previous tag.
Two things to fix, and the second is the durable one:
- Promote, do not append.
[Unreleased] becomes ## <version>, and a fresh empty [Unreleased] is written above it. If commit subjects are still wanted, they belong appended inside that promoted section, bounded by the previous tag.
- A gate check. Nothing catches a duplicate heading, an empty release section, or a
## [Unreleased] that still holds BREAKING — entries at a tagged commit. scripts/gate-steps.ts is the model — it exists because the step count drifted three times. Candidate rules:
- no two
## headings share a version
- a released section is non-empty
- at a tagged commit,
[Unreleased] holds no BREAKING — entry
wiki/Upgrading.md's per-major count matches the BREAKING — count in that section (today it is derived from the whole file, so a migration in the wrong section still counts)
The last one matters most: the count that was supposed to catch this was derived — and a misplaced entry is invisible to a derived count, because it just makes the number smaller.
Manually corrected for 6.0.0 and the duplicate 5.0.1 heading removed; neither correction is mechanised.
Caught while cutting 6.0.0, after the tag was pushed and before the publish was approved.
bun run scripts/release.ts --bump majorgenerates a## <version>section from commit subjects and appends it, leaving the hand-written## [Unreleased]section untouched above it. So the tree ended up as:wiki/Upgrading.mdtells the reader "read the6.0.0section, in order" — and that section did not contain the migration. For a major whose entire value is its upgrade guide, that is the failure the guide exists to prevent.It has happened before.
CHANGELOG.mdcarried two## 5.0.1headings — one auto-generated from commit subjects, one hand-written — from the previous release run. Nobody noticed, which is the argument for a check rather than more care.Also wrong in the generated section: it includes commits that shipped in an earlier release (
#238,#237,#234were 5.0.1), because the range it reads is not bounded by the previous tag.Two things to fix, and the second is the durable one:
[Unreleased]becomes## <version>, and a fresh empty[Unreleased]is written above it. If commit subjects are still wanted, they belong appended inside that promoted section, bounded by the previous tag.## [Unreleased]that still holdsBREAKING —entries at a tagged commit.scripts/gate-steps.tsis the model — it exists because the step count drifted three times. Candidate rules:##headings share a version[Unreleased]holds noBREAKING —entrywiki/Upgrading.md's per-major count matches theBREAKING —count in that section (today it is derived from the whole file, so a migration in the wrong section still counts)The last one matters most: the count that was supposed to catch this was derived — and a misplaced entry is invisible to a derived count, because it just makes the number smaller.
Manually corrected for 6.0.0 and the duplicate 5.0.1 heading removed; neither correction is mechanised.