heavy-duty/ceremony

Fork

You've already forked ceremony

Code Issues 1 Pull requests Projects Releases 8 Packages Wiki Activity Actions

lib/changelog.sh + changelog-armed — the one-shape rule fails the PR that introduces the drift #159

New issue

Closed

opened 2026-07-24 15:43:52 +00:00 by dan-claude-bot · 2 comments

dan-claude-bot commented

2026-07-24 15:43:52 +00:00

(Migrated from github.com)

Copy link

Part of #157. All line references pinned at f168bbf.

Context

The one-shape rule (#112 D4) is enforced in exactly one place: inside changelog_assemble, which compares fragments against each other at assembly time (L185-L192). On a development tree, changelog-armed validates fragments one at a time (L90-L98); a single fragment carrying ### Fixed is individually legal, so nothing in the per-PR path can see the drift. Four PRs (#143, #147, #150, #152) each passed CI with a grouped fragment on this flat repo, and the mix surfaced only when the 0.3.0 cut ran the assembler by hand — the assembler is deliberately not a CI step (bin/changelog-assemble L4), and stays that way.

The consequence is structural: shape drift is always found at release time, by whoever is cutting, never by the change that caused it. This issue moves the rule onto the PR, the same move #112 D9 made for per-fragment malformedness.

Spec

Decisions, per #157 D3:

One definition. A new function in lib/changelog.sh — changelog_shape_problem <changelog> <fragments-dir> — with the same contract as the other *_problem functions: print the first reason and return 1, silence and 0 otherwise. The cross-fragment detection currently inlined in changelog_assemble moves into it (or into a helper both call); changelog_assemble keeps refusing a mixed set with the same diagnosis it prints today, delegating rather than duplicating, so guard and assembler cannot disagree.
Two rules, in order:
1. Cross-fragment: the fragment set is one shape — grouped or flat, never both. The existing diagnoses (mixed set, and a single fragment mixing both shapes) survive verbatim.
2. Anchor: when <changelog> has at least one published ## section, the set's shape must match the newest section's shape (a section is grouped iff its body contains a ### line — changelog_section is the extractor). This is what catches an all-grouped set on a flat repo, which rule 1 structurally cannot. No published section, or an empty fragment set → the rule is vacuous, not a failure.
  A refusal names the offending fragment(s), the expected shape, and where the expectation comes from (the neighbouring fragment, or the published section).
changelog-armed calls it in fragment mode after the per-fragment loop, on every tree. On a bare tree the set must already be empty, so the check is effectively the dev-tree guard — which is the point: it fires on the PR that introduces the drift.
bin/changelog-assemble calls it too, before assembling — it knows the changelog path, so it picks up the anchor rule the lib-level changelog_assemble cannot (that function takes only a directory and does not grow a new argument).
Consumers are unaffected until their pin bump: grouped repos anchor to their own grouped published sections and pass. D8's both-shapes tolerance (no changelog.d/ → today's rules verbatim) is untouched.
One changelog.d/159.md fragment for this PR, flat.

Tasks

Extract the shape check into changelog_shape_problem in lib/changelog.sh; changelog_assemble delegates its mixed-set refusal to the shared code.
Add the anchor rule (newest published section's shape) to changelog_shape_problem.
Wire the call into changelog-armed.sh's fragment mode and into bin/changelog-assemble.
Tests in test/changelog.test.sh / test/changelog-armed.test.sh covering the must-fail and must-pass cases below.
changelog.d/159.md, flat.

Acceptance criteria

A tree with flat published sections and one grouped fragment beside flat ones goes red in changelog-armed — the exact #143 case, individually legal today.
A tree with flat published sections and an all-grouped fragment set goes red — the case cross-fragment comparison alone cannot see.
A mixed set still fails bin/changelog-assemble with the same diagnosis text as today, and now fails changelog-armed with the same shared diagnosis.
A grouped set over grouped published sections passes; a consistent set with no published section passes; an empty directory passes; a flat set over flat sections passes.
The check exists in exactly one function used by both callers — no second copy of the shape logic survives in changelog_assemble or the action.
bash test/run.sh green.

Test plan

Constructed trees per case above, driven the way test/changelog-armed.test.sh already drives the action script.
The must-fail cases are the spec: each red case must name the offending fragment and the source of the expected shape.

Dependencies

Part of #157. Blocked by #158 — changelog-armed self-consumes from the PR's own tree, so this check would refuse its own PR while changelog.d/ is still mixed. Blocks #160 (#157 D6).

Part of #157. All line references pinned at [`f168bbf`](https://github.com/heavy-duty/ceremony/tree/f168bbfbacf5e15825750b338e2a06d47c567cc5). ## Context The one-shape rule (#112 D4) is enforced in exactly one place: inside [`changelog_assemble`](https://github.com/heavy-duty/ceremony/blob/f168bbfbacf5e15825750b338e2a06d47c567cc5/lib/changelog.sh#L167), which compares fragments against each other at assembly time ([L185-L192](https://github.com/heavy-duty/ceremony/blob/f168bbfbacf5e15825750b338e2a06d47c567cc5/lib/changelog.sh#L185-L192)). On a development tree, `changelog-armed` validates fragments **one at a time** ([L90-L98](https://github.com/heavy-duty/ceremony/blob/f168bbfbacf5e15825750b338e2a06d47c567cc5/actions/changelog-armed/changelog-armed.sh#L90-L98)); a single fragment carrying `### Fixed` is individually legal, so nothing in the per-PR path can see the drift. Four PRs (#143, #147, #150, #152) each passed CI with a grouped fragment on this flat repo, and the mix surfaced only when the `0.3.0` cut ran the assembler by hand — the assembler is deliberately not a CI step ([`bin/changelog-assemble` L4](https://github.com/heavy-duty/ceremony/blob/f168bbfbacf5e15825750b338e2a06d47c567cc5/bin/changelog-assemble#L4)), and stays that way. The consequence is structural: shape drift is always found at release time, by whoever is cutting, never by the change that caused it. This issue moves the rule onto the PR, the same move #112 D9 made for per-fragment malformedness. ## Spec Decisions, per #157 D3: - **One definition.** A new function in `lib/changelog.sh` — `changelog_shape_problem <changelog> <fragments-dir>` — with the same contract as the other `*_problem` functions: print the first reason and return 1, silence and 0 otherwise. The cross-fragment detection currently inlined in `changelog_assemble` moves into it (or into a helper both call); `changelog_assemble` keeps refusing a mixed set with the same diagnosis it prints today, delegating rather than duplicating, so guard and assembler cannot disagree. - **Two rules, in order:** 1. *Cross-fragment*: the fragment set is one shape — grouped or flat, never both. The existing diagnoses (mixed set, and a single fragment mixing both shapes) survive verbatim. 2. *Anchor*: when `<changelog>` has at least one published `## ` section, the set's shape must match the **newest** section's shape (a section is grouped iff its body contains a `### ` line — [`changelog_section`](https://github.com/heavy-duty/ceremony/blob/f168bbfbacf5e15825750b338e2a06d47c567cc5/lib/changelog.sh#L17) is the extractor). This is what catches an *all*-grouped set on a flat repo, which rule 1 structurally cannot. No published section, or an empty fragment set → the rule is vacuous, not a failure. A refusal names the offending fragment(s), the expected shape, and where the expectation comes from (the neighbouring fragment, or the published section). - **`changelog-armed` calls it** in fragment mode after the per-fragment loop, on every tree. On a bare tree the set must already be empty, so the check is effectively the dev-tree guard — which is the point: it fires on the PR that introduces the drift. - **`bin/changelog-assemble` calls it too**, before assembling — it knows the changelog path, so it picks up the anchor rule the lib-level `changelog_assemble` cannot (that function takes only a directory and does not grow a new argument). - **Consumers are unaffected until their pin bump**: grouped repos anchor to their own grouped published sections and pass. D8's both-shapes tolerance (no `changelog.d/` → today's rules verbatim) is untouched. - One `changelog.d/159.md` fragment for this PR, flat. ## Tasks - [ ] Extract the shape check into `changelog_shape_problem` in `lib/changelog.sh`; `changelog_assemble` delegates its mixed-set refusal to the shared code. - [ ] Add the anchor rule (newest published section's shape) to `changelog_shape_problem`. - [ ] Wire the call into `changelog-armed.sh`'s fragment mode and into `bin/changelog-assemble`. - [ ] Tests in `test/changelog.test.sh` / `test/changelog-armed.test.sh` covering the must-fail and must-pass cases below. - [ ] `changelog.d/159.md`, flat. ## Acceptance criteria - [ ] A tree with flat published sections and **one** grouped fragment beside flat ones goes red in `changelog-armed` — the exact #143 case, individually legal today. - [ ] A tree with flat published sections and an **all-grouped** fragment set goes red — the case cross-fragment comparison alone cannot see. - [ ] A mixed set still fails `bin/changelog-assemble` with the same diagnosis text as today, and now fails `changelog-armed` with the same shared diagnosis. - [ ] A grouped set over grouped published sections passes; a consistent set with no published section passes; an empty directory passes; a flat set over flat sections passes. - [ ] The check exists in exactly one function used by both callers — no second copy of the shape logic survives in `changelog_assemble` or the action. - [ ] `bash test/run.sh` green. ## Test plan - Constructed trees per case above, driven the way `test/changelog-armed.test.sh` already drives the action script. - The must-fail cases are the spec: each red case must name the offending fragment and the source of the expected shape. ## Dependencies Part of #157. Blocked by #158 — `changelog-armed` self-consumes from the PR's own tree, so this check would refuse its own PR while `changelog.d/` is still mixed. Blocks #160 (#157 D6).

github-actions[bot] commented

2026-07-24 16:06:51 +00:00

(Migrated from github.com)

Copy link

Every issue named by Blocked by is closed. The sweep is moving this issue to ready.

Every issue named by `Blocked by` is closed. The sweep is moving this issue to `ready`.

codex-bot-andresmgsl commented

2026-07-24 16:11:50 +00:00

(Migrated from github.com)

Copy link

Claimed by @codex-bot-andresmgsl. I am starting implementation now and will open a draft PR after the first commit.

No Branch/Tag specified

Branches Tags

main

build/275-merge-base-release-shape

build/273-resume-merge-door

build/271-atomic-forgejo-release

build/269-upstream-sync-record

release-0.6.3

build/265-needs-triage-description

build/263-consume-stranded-changelog

build/247-proposal-intake

build/243-forgejo-workflow-name

build/251-release-path-doc

build/241-fork-labels

probe/241-same-head

build/253-stranded-fragments

build/240-exhaustive-timeline

build/234-bind-refs-token

build/238-review-requests

build/231-release-0-6-2

build/246-upstream-release-fragment

0.6.3

0.6.2

0.6.1

0.4.1

0.4.0

0.3.0

0.2.0

0.1.0

Labels

Clear labels

attention

A demand is parked here for the assignee: pick up the thread, ack by removing this label

blocked

Waiting on another PR or issue to land first

blocker:ci-red

A check is failing — the agent owes a fix (not a rebase)

blocker:conflict

Does not merge — the branch conflicts and the agent owes a rebase

blocker:drill-pending

A release PR whose version has no drills/X.Y.Z.md record — correct but unevidenced

blocker:unrequested

Somebody still owes a verdict and nobody was asked for one

bug

Something isn't working

claimed

A builder owns it: assignee set, draft PR expected shortly

documentation

Improvements or additions to documentation

enhancement

New feature or request

epic

Organizes other issues via a dependency-ordered task list — builders never pick it

merge-next

Head of the merge queue — merge this one next (set by hand/agent, cleared here)

needs-ruling

A human decision is pending — question, options and a recommendation are in the comment

needs-triage

Did not come through triage — owes normalization into work or a reasoned refusal

offsite

Issue deliverable is a PR in another repository — claim clock paused

post-merge

Refs-linked PR merged; post-merge criteria remain and triage owns completion

ready

Triaged, spec complete, unblocked — a builder can start now and succeed

release

Release flow and version/packaging work

scope:docs

README doctrine, CONSUMERS.md, the role files

scope:guards

changelog-armed / changelog-monotonic / drill-recorded

scope:labels

The labels workflow, reconciler, the taxonomy

scope:release-flow

The reusable release workflow, decide, the doors

stale

No activity for 48h — needs a poke (sweep-managed)

state:addressing

All bots reviewed — coding agent owes the single reply + fixes

state:bots-reviewing

Waiting on the bot reviewers to finish the round

state:building

Pre-round: the builder is still building — draft is evidence for it, not the definition

state:needs-human

No blockers, all bots approve — waiting on the human reviewer

No labels

blocker:drill-pending

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

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: heavy-duty/ceremony#159

Reference in a new issue

Repository

heavy-duty/ceremony

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?