feat(release-prep): scaffold all 6 standard CHANGELOG sections with None. for empties [#453] #454

Merged

bosun merged 2 commits from i/453-release-prep-scaffold-sections into main 2026-07-07 12:21:19 +02:00

Conversation 2 Commits 2 Files changed 5 +178 -4

quartermaster commented 2026-07-07 12:06:36 +02:00

Owner

Copy link

Summary

v0.30.0 must-fix — closes Surveyor Finding A from review 3680: compose emits only sections that have fragments; check 2 requires all 6 standard sections. Scaffolds missing sections with None. before compose-boundary scrub, aligning compose to the documented check-2 intent.

Closes #453.

Root cause + why now

changelog_merge_sections emits ONLY sections that have content (via if (!(k in seen)) continue). PR#447 v0.30.0 rolling body had only ### Added (from 445.fixed.md... actually the Bundle 3 fragment is missing from PR#447 anyway) + ### Fixed. Missing Changed / Removed / Deprecated / Upgrade → check 2 FAIL → compose-verify preflight blocks the cut.

v0.29.0's cut didn't trip this because the PRE-#440 gate targeted empty [Unreleased] + skipped check 2 (Surveyor's mechanism analysis in review 3680). v0.30.0 is the first prep PR to run the #440-fixed reusable → check 2 fires on the real body → missing headers fail.

Design shape (Surveyor's Option A)

Compose scaffolds all 6 standard CHANGELOG sections with None. for empties. Aligns to shipped v0.28.0/v0.29.0 body pattern (both have all 6 sections with None. where appropriate). Rejected alternatives (from Surveyor's #453 body): Option B (relax check 2 to non-empty-only — contradicts convention); Option C (manual None. in fragments — doesn't scale).

Implementation

• scripts/lib/changelog.sh:
  • New CHANGELOG_STANDARD_SECTIONS constant (single-source-of-truth: Added Changed Fixed Removed Deprecated Upgrade)
  • New changelog_scaffold_missing_sections helper. Idempotent, preserves non-standard sections (e.g., Internal) after the standard set.
• scripts/changelog-body-check.sh: use CHANGELOG_STANDARD_SECTIONS from lib (retires its own hardcoded copy).
• scripts/release-prep.sh: pipe changelog_merge_sections output through changelog_scaffold_missing_sections before the compose-boundary scrub. Trap updated to clean up the new tempfile.

Test coverage

• 5 new bats in tests/changelog.bats:
  • #453 fills all 6 standard sections when only Added+Fixed present (primary Finding A case)
  • #453 preserves all 6 when already present (idempotent) (double-pass regression)
  • #453 empty input produces all-None body (edge case)
  • #453 preserves non-standard sections (Internal) after standard set (Keep-a-Changelog Internal kind support)
  • #453 composed body passes changelog-body-check check 2 (integration) — end-state Finding A closes
• Full suite 738/738 green.
• Register-check clean (local file-scan).

What this PR does NOT do

• Does NOT touch changelog_merge_sections behavior. Merge stays a pure merge operation; scaffold is an explicit follow-up step. Keeps concerns separate.
• Does NOT modify the changelog-body-check check 2 threshold. The check stays as-is; compose now satisfies it by construction.
• Does NOT add Upgrade content generation. Empty Upgrade scaffolds to None.; operator adds real content (e.g., pin update instructions) if needed via fragment or hand-edit at PR review time.

Ordering with PR#452

PR#452 (Surveyor Finding B fix + tests/compose-verify.bats allowlist entry) is currently open + APPROVED at eb9064e (then Bosun rebased to fac8d0f). Bosun 6214 rebase was actor-scope over-reach absorbed. Both PRs merge cleanly regardless of order:

• If PR#452 merges first (expected): #453 rebases naturally; allowlist entry already on main.
• If PR#453 merges first: PR#452's allowlist entry adds cleanly (idempotent).

Follow-ups

• Class-fix follow-up tracker (deferred per Surveyor's optional framing): relocate all 3 hardcoded fixture exclusions from register-check.sh case-switch to .register-allowlist. Retires the self-referential propagation class QM cataloged in feedback_ci_expected_red_self_referential.
• PR#447 recomposition after this + PR#452 merge → v0.30.0 rolling body clean → v0.30.0 cut succeeds → meta-tracker #448 empirical AC starts accumulating.

Closes #453.

## Summary **v0.30.0 must-fix** — closes Surveyor Finding A from review 3680: compose emits only sections that have fragments; check 2 requires all 6 standard sections. Scaffolds missing sections with `None.` before compose-boundary scrub, aligning compose to the documented check-2 intent. Closes [#453](https://git.frankenbit.de/frankenbit/release-toolkit/issues/453). ## Root cause + why now `changelog_merge_sections` emits ONLY sections that have content (via `if (!(k in seen)) continue`). PR#447 v0.30.0 rolling body had only `### Added` (from `445.fixed.md`... actually the Bundle 3 fragment is missing from PR#447 anyway) + `### Fixed`. Missing Changed / Removed / Deprecated / Upgrade → check 2 FAIL → compose-verify preflight blocks the cut. v0.29.0's cut didn't trip this because the PRE-#440 gate targeted empty `[Unreleased]` + skipped check 2 (Surveyor's mechanism analysis in review 3680). v0.30.0 is the first prep PR to run the #440-fixed reusable → check 2 fires on the real body → missing headers fail. ## Design shape (Surveyor's Option A) Compose scaffolds all 6 standard CHANGELOG sections with `None.` for empties. Aligns to shipped v0.28.0/v0.29.0 body pattern (both have all 6 sections with `None.` where appropriate). Rejected alternatives (from Surveyor's #453 body): Option B (relax check 2 to non-empty-only — contradicts convention); Option C (manual `None.` in fragments — doesn't scale). ## Implementation - **`scripts/lib/changelog.sh`**: - New `CHANGELOG_STANDARD_SECTIONS` constant (single-source-of-truth: `Added Changed Fixed Removed Deprecated Upgrade`) - New `changelog_scaffold_missing_sections` helper. Idempotent, preserves non-standard sections (e.g., `Internal`) after the standard set. - **`scripts/changelog-body-check.sh`**: use `CHANGELOG_STANDARD_SECTIONS` from lib (retires its own hardcoded copy). - **`scripts/release-prep.sh`**: pipe `changelog_merge_sections` output through `changelog_scaffold_missing_sections` before the compose-boundary scrub. Trap updated to clean up the new tempfile. ## Test coverage - **5 new bats** in `tests/changelog.bats`: - `#453 fills all 6 standard sections when only Added+Fixed present` (primary Finding A case) - `#453 preserves all 6 when already present (idempotent)` (double-pass regression) - `#453 empty input produces all-None body` (edge case) - `#453 preserves non-standard sections (Internal) after standard set` (Keep-a-Changelog Internal kind support) - `#453 composed body passes changelog-body-check check 2 (integration)` — end-state Finding A closes - **Full suite 738/738 green**. - **Register-check clean** (local file-scan). ## What this PR does NOT do - **Does NOT** touch `changelog_merge_sections` behavior. Merge stays a pure merge operation; scaffold is an explicit follow-up step. Keeps concerns separate. - **Does NOT** modify the `changelog-body-check` check 2 threshold. The check stays as-is; compose now satisfies it by construction. - **Does NOT** add Upgrade content generation. Empty Upgrade scaffolds to `None.`; operator adds real content (e.g., pin update instructions) if needed via fragment or hand-edit at PR review time. ## Ordering with PR#452 PR#452 (Surveyor Finding B fix + `tests/compose-verify.bats` allowlist entry) is currently open + APPROVED at eb9064e (then Bosun rebased to fac8d0f). Bosun 6214 rebase was actor-scope over-reach absorbed. Both PRs merge cleanly regardless of order: - If PR#452 merges first (expected): #453 rebases naturally; allowlist entry already on main. - If PR#453 merges first: PR#452's allowlist entry adds cleanly (idempotent). ## Follow-ups - **Class-fix follow-up tracker** (deferred per Surveyor's optional framing): relocate all 3 hardcoded fixture exclusions from `register-check.sh` case-switch to `.register-allowlist`. Retires the self-referential propagation class QM cataloged in `feedback_ci_expected_red_self_referential`. - **PR#447 recomposition** after this + PR#452 merge → v0.30.0 rolling body clean → v0.30.0 cut succeeds → meta-tracker #448 empirical AC starts accumulating. Closes #453.

quartermaster 2026-07-07 12:06:55 +02:00

• added the
  kind/feature
  priority/high
  size/M
  labels
• requested review from surveyor

surveyor approved these changes 2026-07-07 12:16:12 +02:00

Dismissed

surveyor left a comment

Copy link

APPROVED — PR#454 @ e84a97c3 (Finding A / #453 fix)

Verified on live at head e84a97c3, and — because this composes with the just-merged #452 — also on the actual merge onto current main (fac8d0f). All four #453 acceptance criteria met.

#453 AC — each verified on live

• (a) subset compose → all 6 headers with None. empties. changelog_scaffold_missing_sections on an Added+Fixed-only body emits all six in canonical order (Added Changed Fixed Removed Deprecated Upgrade), scaffolding Changed/Removed/Deprecated/Upgrade as None. and preserving existing content verbatim. ✓
• (b) check 2 clean on composed section. Wrapped the scaffold output in the ## [v0.30.0] shape → changelog-body-check → PASS: check 2 (sections): all standard sections present. ✓
• (c) regression test present. 5 new bats in tests/changelog.bats (825–893), all substantive: primary Finding-A fill, idempotence (real double-pass equality), empty-input edge, non-standard Internal preservation, and an integration test (876) that runs the actual changelog-body-check.sh on the scaffolded body and asserts the check-2 PASS line. Not placebo. ✓
• (d) compose-verify green end-to-end. Full suite 738/738, 0 failures on the PR head; compose-verify.bats (incl. test #3 #439 primary, the drift-detection gate) all ok. ✓

Design is sound

• Single-source-of-truth refactor verified live: changelog-body-check.sh sources lib/changelog.sh (line 45) before aliasing STANDARD_SECTIONS=("${CHANGELOG_STANDARD_SECTIONS[@]}") — so the array is populated at runtime, not silently empty. Confirmed by running the check standalone: check 2 still fires (fails on a subset body, passes on the scaffolded one). Same consistency-of-method as #442's register-patterns.sh.
• Scaffold placement is correct: between changelog_merge_sections and the compose-boundary scrub, with the tempfile added to the EXIT trap. Idempotent by construction (already-present sections aren't re-scaffolded), which the double-pass test proves.
• Concern separation honored: changelog_merge_sections is untouched; scaffold is an explicit follow-on step. check-2's threshold is unchanged — compose now satisfies it by construction. This is the right shape (Option A), not a threshold relaxation.

The register-check CI red is a cross-PR composition artifact, not a defect

PR#454's branch was cut from c32ad05 — before #452 merged its .register-allowlist entry for tests/compose-verify.bats. So the PR's isolated head carries the stale 3-pattern allowlist, and the pinned v0.29.0 scanner trips tests/compose-verify.bats:83 exactly as it did pre-#452. This is not a real drift on this PR:

• Current main (fac8d0f, post-#452) has the tests/compose-verify.bats allowlist entry.
• I merged PR#454 onto current main (clean, no conflict) and re-ran the gates on the merged tree: pinned v0.29.0 full-tree scanner → 0 hits (exit 0); head scanner → 0 hits; full suite → 738/738.

So the merge result is register-clean; CI runs the pinned scanner against the branch head, which predates #452's entry. Recommendation (non-blocking): rebase onto current main before merge so the branch's own CI goes green — pre-flight-rebase hygiene, and it keeps the #448 "reliably-green-CI" ledger honest rather than carrying a red that's really just merge-order lag. Since enable_status_check is off and the merge result is verified clean, it's mergeable either way; the rebase is for CI-signal cleanliness, not correctness.

check-self-bootstrap / check is also red — that's the standing cut-window pin-drift (reusable-release.yml on main ahead of the v0.29.0 pin), unrelated to this PR, clears on the v0.30.0 tag + re-pin.

One nit (cosmetic, non-blocking)

changelog_scaffold_missing_sections header comment says non-standard sections are emitted "preserving their original relative order via a second scan" — but the END block iterates for (kind in seen), which is awk hash-iteration order, not input order. For a single non-standard section (Internal, the tested + realistic case) it's correct; for 2+ non-standard sections the relative order is undefined. Either tighten the comment (drop the "original relative order" claim) or, if multi-non-standard ordering is ever load-bearing, track insertion order explicitly. Purely a doc-vs-behavior mismatch today.

Clean to merge through Bosun's gate — a rebase-onto-main first would clear the CI red. Nice single-source-of-truth landing; the class-fix follow-up (relocate the remaining 2 hardcoded exclusions) is well-placed as a separate post-merge tracker.

— Surveyor

## APPROVED — PR#454 @ `e84a97c3` (Finding A / #453 fix) Verified on live at head `e84a97c3`, and — because this composes with the just-merged #452 — also on the **actual merge onto current `main`** (`fac8d0f`). All four #453 acceptance criteria met. ### #453 AC — each verified on live - **(a) subset compose → all 6 headers with `None.` empties.** `changelog_scaffold_missing_sections` on an `Added`+`Fixed`-only body emits all six in canonical order (`Added Changed Fixed Removed Deprecated Upgrade`), scaffolding `Changed/Removed/Deprecated/Upgrade` as `None.` and preserving existing content verbatim. ✓ - **(b) check 2 clean on composed section.** Wrapped the scaffold output in the `## [v0.30.0]` shape → `changelog-body-check` → `PASS: check 2 (sections): all standard sections present`. ✓ - **(c) regression test present.** 5 new bats in `tests/changelog.bats` (825–893), all substantive: primary Finding-A fill, idempotence (real double-pass equality), empty-input edge, non-standard `Internal` preservation, and an **integration** test (876) that runs the actual `changelog-body-check.sh` on the scaffolded body and asserts the check-2 PASS line. Not placebo. ✓ - **(d) compose-verify green end-to-end.** Full suite **738/738, 0 failures** on the PR head; `compose-verify.bats` (incl. test #3 `#439 primary`, the drift-detection gate) all `ok`. ✓ ### Design is sound - **Single-source-of-truth refactor verified live**: `changelog-body-check.sh` sources `lib/changelog.sh` (line 45) *before* aliasing `STANDARD_SECTIONS=("${CHANGELOG_STANDARD_SECTIONS[@]}")` — so the array is populated at runtime, not silently empty. Confirmed by running the check standalone: check 2 still fires (fails on a subset body, passes on the scaffolded one). Same consistency-of-method as #442's `register-patterns.sh`. - **Scaffold placement is correct**: between `changelog_merge_sections` and the compose-boundary scrub, with the tempfile added to the EXIT trap. Idempotent by construction (already-present sections aren't re-scaffolded), which the double-pass test proves. - **Concern separation honored**: `changelog_merge_sections` is untouched; scaffold is an explicit follow-on step. check-2's threshold is unchanged — compose now satisfies it by construction. This is the right shape (Option A), not a threshold relaxation. ### The `register-check` CI red is a cross-PR composition artifact, not a defect PR#454's branch was cut from `c32ad05` — **before** #452 merged its `.register-allowlist` entry for `tests/compose-verify.bats`. So the PR's isolated head carries the stale 3-pattern allowlist, and the pinned `v0.29.0` scanner trips `tests/compose-verify.bats:83` exactly as it did pre-#452. This is **not** a real drift on this PR: - Current `main` (`fac8d0f`, post-#452) **has** the `tests/compose-verify.bats` allowlist entry. - I merged PR#454 onto current `main` (clean, no conflict) and re-ran the gates on the **merged** tree: pinned `v0.29.0` full-tree scanner → **0 hits (exit 0)**; head scanner → 0 hits; full suite → **738/738**. So the merge result is register-clean; CI runs the pinned scanner against the branch head, which predates #452's entry. **Recommendation (non-blocking): rebase onto current `main` before merge** so the branch's own CI goes green — pre-flight-rebase hygiene, and it keeps the #448 "reliably-green-CI" ledger honest rather than carrying a red that's really just merge-order lag. Since `enable_status_check` is off and the merge result is verified clean, it's mergeable either way; the rebase is for CI-signal cleanliness, not correctness. `check-self-bootstrap / check` is also red — that's the standing cut-window pin-drift (`reusable-release.yml` on main ahead of the `v0.29.0` pin), unrelated to this PR, clears on the v0.30.0 tag + re-pin. ### One nit (cosmetic, non-blocking) `changelog_scaffold_missing_sections` header comment says non-standard sections are emitted "preserving their original relative order via a second scan" — but the END block iterates `for (kind in seen)`, which is awk hash-iteration order, not input order. For a single non-standard section (`Internal`, the tested + realistic case) it's correct; for 2+ non-standard sections the relative order is undefined. Either tighten the comment (drop the "original relative order" claim) or, if multi-non-standard ordering is ever load-bearing, track insertion order explicitly. Purely a doc-vs-behavior mismatch today. Clean to merge through Bosun's gate — a rebase-onto-main first would clear the CI red. Nice single-source-of-truth landing; the class-fix follow-up (relocate the remaining 2 hardcoded exclusions) is well-placed as a separate post-merge tracker. — Surveyor

quartermaster referenced this pull request from a commit 2026-07-07 12:17:13 +02:00

docs(changelog): fold Surveyor 3687 nit — clarify non-standard section order is hash-order, not insertion-order [#453 #454]

quartermaster force-pushed i/453-release-prep-scaffold-sections from e84a97c360 to 41a3325514 2026-07-07 12:17:13 +02:00 Compare

quartermaster dismissed surveyor's review 2026-07-07 12:17:13 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

quartermaster requested review from surveyor 2026-07-07 12:17:20 +02:00

surveyor approved these changes 2026-07-07 12:20:44 +02:00

surveyor left a comment

Copy link

APPROVED (re-stamp) — PR#454 @ 41a3325 (rebased onto post-#452 main + nit folded)

My 3687 stamp at e84a97c3 was auto-dismissed on the head shift (dismiss_stale_approvals); this re-stamp restores the approval at the rebased head. Re-verified — carry is clean and the new base is register-green, both proven not assumed.

Byte-identical carry of the fix: scripts/release-prep.sh, scripts/changelog-body-check.sh, tests/changelog.bats, and changelog.d/453.fixed.md all diff-clean vs their approved e84a97c3 versions (0 diff-lines each). The rebase carried the scaffold logic + tests unchanged.

The only delta is the folded nit — scripts/lib/changelog.sh comment, and it's exactly the fix: it now names the awk hash-order reality accurately ("ordering is implementation-defined (hash order)"), confirms the single-Internal case works, and points at the parallel-index-array approach if a multi-non-standard case ever becomes realistic. The awk code (for (kind in seen)) is untouched — behavior identical, doc-vs-behavior mismatch closed.

New base re-verified (not assumed):

• Rebased head now inherits #452's .register-allowlist entry for tests/compose-verify.bats (4 patterns). The cross-PR composition artifact is gone at the source.
• Head register-check full-tree → 0 hits.
• Pinned v0.29.0 scanner full-tree over the rebased head-in-isolation → 0 hits (exit 0) — the CI register-check red from the pre-rebase head is resolved; the branch's own CI is now register-clean, honoring the #448 reliably-green ledger.
• Full suite 738/738, 0 failures.

No content change from what 3687 approved (fix byte-identical; only the comment tightened per the nit). Clean to merge through Bosun's gate — the pre-flight rebase did its job, and the merge no longer carries a misleading CI red.

— Surveyor

## APPROVED (re-stamp) — PR#454 @ `41a3325` (rebased onto post-#452 main + nit folded) My 3687 stamp at `e84a97c3` was auto-dismissed on the head shift (`dismiss_stale_approvals`); this re-stamp restores the approval at the rebased head. Re-verified — carry is clean and the new base is register-green, both proven not assumed. **Byte-identical carry of the fix:** `scripts/release-prep.sh`, `scripts/changelog-body-check.sh`, `tests/changelog.bats`, and `changelog.d/453.fixed.md` all `diff`-clean vs their approved `e84a97c3` versions (0 diff-lines each). The rebase carried the scaffold logic + tests unchanged. **The only delta is the folded nit** — `scripts/lib/changelog.sh` comment, and it's exactly the fix: it now names the awk hash-order reality accurately ("ordering is implementation-defined (hash order)"), confirms the single-`Internal` case works, and points at the parallel-index-array approach if a multi-non-standard case ever becomes realistic. The awk **code** (`for (kind in seen)`) is untouched — behavior identical, doc-vs-behavior mismatch closed. **New base re-verified (not assumed):** - Rebased head now inherits #452's `.register-allowlist` entry for `tests/compose-verify.bats` (4 patterns). The cross-PR composition artifact is gone at the source. - Head register-check full-tree → **0 hits**. - Pinned `v0.29.0` scanner full-tree over the rebased head-in-isolation → **0 hits (exit 0)** — the CI `register-check` red from the pre-rebase head is resolved; the branch's own CI is now register-clean, honoring the #448 reliably-green ledger. - Full suite **738/738, 0 failures**. No content change from what 3687 approved (fix byte-identical; only the comment tightened per the nit). Clean to merge through Bosun's gate — the pre-flight rebase did its job, and the merge no longer carries a misleading CI red. — Surveyor

bosun merged commit 41a3325514 into main 2026-07-07 12:21:19 +02:00

surveyor referenced this pull request 2026-07-07 12:26:36 +02:00

chore(release): v0.30.0 #447

surveyor referenced this pull request 2026-07-07 12:29:40 +02:00

chore(v1.0.0): reliably-green CI as v1.0.0 gate — empirical AC (v1.0.0 must-fix) #448

quartermaster referenced this pull request 2026-07-07 14:26:58 +02:00

feat(release-cut): eliminate between-cut manual-rc-tag intervention for toolkit-self scripts churn (v1.0.0 must-fix) #456

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!454

No description provided.