frankenbit/release-toolkit

Fork 0

docs(changelog.d): distill six v0.35.0 fragments to the template brevity rule #628

Merged

alex merged 1 commit from i/627-distill-v0.35.0-fragments into main

2026-07-31 15:27:48 +02:00

herald commented

2026-07-31 15:19:55 +02:00

Owner

Alex asked for the slim look back on the composed v0.35.0 entry. Measurement and
framing are on #627; this PR is the fragment-side distillation.

The axis

changelog.d/.template.md asks for outcome + required action in 1-3 sentences,
with "mechanism, root cause, why-it-broke narratives belong in the PR body, NOT the
fragment." Four of the six were 2+ paragraphs. All six passed every check before this
PR and all six pass every check after it — checks 7 and 9 do not measure this axis,
which is why the fix targets the template's own rule instead.

	chars	paragraphs
six fragments, before	2855	1·2·1·3·2·1
six fragments, after	1874	all 1
composed body	3037 → 2056	prose blocks 21 → 13

Verification

Composed a faithful body (.added.md → Added, .fixed.md → Fixed) and ran the real
scripts/changelog-body-check.sh on it, plus the same gate on the originals as a
control and a deliberately-overlong sentence as a negative control:

DISTILLED   check 4  2056 chars   check 7 ≤25w PASS   check 9 ≤75w PASS
ORIGINALS   check 4  3037 chars   check 7 ≤25w PASS   check 9 ≤75w PASS   ← gate is blind to the axis
NEGATIVE    FAIL: check 7 sentence(s) exceed 30 words                     ← so the PASSes are measurements

scripts/fragment-check.sh: exit 0.

⚠️ Check 5 still soft-warns (mixed bullet+prose in Added): the section mixes
fragment prose with a commit-subject bullet. Two sources, one section — #627's
problem, deliberately not chased here.

What moved out of the fragments (the mechanism prose, per the template)

476-manifest-check — last-tag discovery skips prerelease tags, so a closer -rc
tag cannot falsely trip "manifest BEHIND tag"; that also hid every tag in a
v1.0.0-alpha.N series. When the manifest is itself a prerelease, the newest tag
including prereleases is now used. Across a whole alpha/beta/rc run the old
behaviour could not report drift at all.
476-prep — a prerelease cut walks the CHANGELOG from the preceding prerelease
tag rather than the last stable one.
476-semver-prerelease-bump — plain semver_bump cannot express the cadence:
per SemVer's release semantics it drops the prerelease suffix. The refusal rule
includes starting a series on a release version, which SemVer §11 orders below
that release.
476-decide — the shell and Go implementations agree.
605 — unchanged in substance; the "green means the check could not run"
disclosure is preserved verbatim in meaning (it is a required-action warning, not
mechanism, and #612's review established it as load-bearing).
612 — the digit-count-then-lexical comparison needs no machine integers.

Two refs added, flagged rather than silent

476-manifest-check and 476-semver-prerelease-bump carried no (#NNN) ref at all.
Both gained (#476) — the template's shape requires it and their four siblings already
had it. Every other code literal and ref is byte-identical. Revert those two tokens if
the preference is strict preservation.

Why on `main`, not the composed CHANGELOG

release-prep force-recreates the rolling branch from main at every regeneration, so
an edit to the composed section is destroyed by the next cut while an edit to the
fragment survives it. Same reasoning as #619.

Refs #627. No close keyword — #627 is the measurement write-up and closing it is not
this PR's call.

Alex asked for the slim look back on the composed v0.35.0 entry. Measurement and framing are on #627; this PR is the fragment-side distillation. ## The axis `changelog.d/.template.md` asks for **outcome + required action in 1-3 sentences**, with *"mechanism, root cause, why-it-broke narratives belong in the PR body, NOT the fragment."* Four of the six were 2+ paragraphs. All six passed every check before this PR and all six pass every check after it — **checks 7 and 9 do not measure this axis**, which is why the fix targets the template's own rule instead. | | chars | paragraphs | |---|---|---| | six fragments, before | 2855 | 1·2·1·3·2·1 | | six fragments, after | **1874** | all 1 | | composed body | 3037 → **2056** | prose blocks 21 → 13 | ## Verification Composed a faithful body (`.added.md` → Added, `.fixed.md` → Fixed) and ran the real `scripts/changelog-body-check.sh` on it, plus the same gate on the **originals** as a control and a deliberately-overlong sentence as a **negative** control: ``` DISTILLED check 4 2056 chars check 7 ≤25w PASS check 9 ≤75w PASS ORIGINALS check 4 3037 chars check 7 ≤25w PASS check 9 ≤75w PASS ← gate is blind to the axis NEGATIVE FAIL: check 7 sentence(s) exceed 30 words ← so the PASSes are measurements ``` `scripts/fragment-check.sh`: exit 0. ⚠️ **Check 5 still soft-warns** (`mixed bullet+prose in Added`): the section mixes fragment prose with a commit-subject bullet. Two sources, one section — **#627's problem, deliberately not chased here.** ## What moved out of the fragments (the mechanism prose, per the template) - **`476-manifest-check`** — last-tag discovery skips prerelease tags, so a closer `-rc` tag cannot falsely trip *"manifest BEHIND tag"*; that also hid every tag in a `v1.0.0-alpha.N` series. When the manifest is itself a prerelease, the newest tag *including* prereleases is now used. Across a whole alpha/beta/rc run the old behaviour could not report drift at all. - **`476-prep`** — a prerelease cut walks the CHANGELOG from the preceding prerelease tag rather than the last stable one. - **`476-semver-prerelease-bump`** — plain `semver_bump` cannot express the cadence: per SemVer's release semantics it drops the prerelease suffix. The refusal rule includes starting a series on a release version, which SemVer §11 orders *below* that release. - **`476-decide`** — the shell and Go implementations agree. - **`605`** — unchanged in substance; the *"green means the check could not run"* disclosure is preserved verbatim in meaning (it is a required-action warning, not mechanism, and #612's review established it as load-bearing). - **`612`** — the digit-count-then-lexical comparison needs no machine integers. ## Two refs added, flagged rather than silent `476-manifest-check` and `476-semver-prerelease-bump` carried **no `(#NNN)` ref at all**. Both gained `(#476)` — the template's shape requires it and their four siblings already had it. Every other code literal and ref is byte-identical. **Revert those two tokens if the preference is strict preservation.** ## Why on `main`, not the composed CHANGELOG `release-prep` force-recreates the rolling branch from `main` at every regeneration, so an edit to the composed section is destroyed by the next cut while an edit to the fragment survives it. Same reasoning as #619. Refs #627. **No close keyword** — #627 is the measurement write-up and closing it is not this PR's call.

herald added 1 commit

2026-07-31 15:19:55 +02:00

docs(changelog.d): distill six v0.35.0 fragments to the template brevity rule

check-self-bootstrap / check (pull_request) Successful in 3s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 4s

Details

fragment-check / check (pull_request) Successful in 0s

Details

go-ci / lint + build + test (pull_request) Successful in 33s

Details

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s

Details

manifest-check / check (pull_request) Successful in 0s

Details

tests / bats (pull_request) Successful in 2m8s

Details

tests / shellcheck (pull_request) Successful in 8s

Details

check-self-bootstrap / check (push) Successful in 3s

Details

go-ci / lint + build + test (push) Successful in 31s

Details

release / decide + act (push) Successful in 8s

Details

release / release (push) Successful in 0s

Details

tests / bats (push) Successful in 2m8s

Details

tests / shellcheck (push) Successful in 8s

Details

d20ad5e270

The six fragments consumed by the v0.35.0 cut carried multi-paragraph
mechanism prose. `changelog.d/.template.md` asks for "outcome + required
action in 1-3 sentences", with mechanism, root cause and why-it-broke
narratives in the PR body instead. Four of the six were 2+ paragraphs.

Distilled on `main` rather than on the composed CHANGELOG: release-prep
force-recreates the rolling branch from `main` at every regeneration, so
an edit to the composed section is destroyed by the next cut while an
edit to the fragment survives it. Same reasoning as #619.

Code literals and (#NNN) refs preserved byte-identically. Two fragments
(476-manifest-check, 476-semver-prerelease-bump) carried no issue ref at
all; both gained (#476), which the template's own shape requires and
their four siblings already had.

Mechanism prose removed here is reproduced in the PR body.

2855 -> 1910 chars across the six; composed body 3037 -> 2056.
Refs #627.