From ecb0371cad31397e4e07882e64fd9eca7cfc5a25 Mon Sep 17 00:00:00 2001 From: dan-claude-bot Date: Sun, 2 Aug 2026 13:27:06 +0000 Subject: [PATCH] docs: clear five stale unreleased markers; the release PR owns clearing Each marker now says available-at-tag in the guide's existing L420 phrasing, verified by tag containment in #221; every never-mix-refs sentence survives verbatim. The convention paragraph gains its missing half: the release PR that ships machinery clears, in that same PR, every marker its assembled section makes false. Refs #221 Co-Authored-By: Claude Fable 5 --- changelog.d/221.md | 9 +++++++++ docs/CONSUMERS.md | 44 +++++++++++++++++++++++++------------------- 2 files changed, 34 insertions(+), 19 deletions(-) create mode 100644 changelog.d/221.md diff --git a/changelog.d/221.md b/changelog.d/221.md new file mode 100644 index 0000000..e1b4997 --- /dev/null +++ b/changelog.d/221.md @@ -0,0 +1,9 @@ +### Fixed + +- Five stale **unreleased** markers in `docs/CONSUMERS.md` now name their + tags: fragment mode, `changelog-assembled` and `runner-isolated` at + `0.2.0`; the additive labeler at `0.3.0`; the two-caller split at `0.4.1` + (#221). +- The marker convention now names its clearing owner: the release PR that + ships machinery clears, in that same PR, every marker its assembled + section makes false (#221). diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 0afb58c..e00e085 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -60,10 +60,10 @@ the machinery at all: the release PR assembles the section ([Assembling a release section](#assembling-a-release-section)). - Fragment mode is **unreleased** and not in `0.1.0`. A consumer pinned - to `0.1.0` bootstraps the legacy shape instead — the preamble plus an - empty `## Unreleased` section for entries to land under — and converts - on the pin bump to the first tag carrying fragment mode; never mix + Fragment mode is available at `0.2.0` and later, and not in `0.1.0`. + A consumer pinned to `0.1.0` bootstraps the legacy shape instead — the + preamble plus an empty `## Unreleased` section for entries to land + under — and converts on the pin bump to `0.2.0` or later; never mix refs to adopt it early. 3. **`drills/README.md`** defining what a drill *means* in this repo — each repo names its own @@ -85,14 +85,16 @@ the machinery at all: fetch-depth: 0 - uses: heavy-duty/ceremony/actions/changelog-armed@ - uses: heavy-duty/ceremony/actions/changelog-monotonic@ - # Unreleased: changelog-assembled is not in 0.1.0. Adopt this step - # with the pin bump to the first tag that carries it; never mix - # refs. Green NOTICE on every non-release PR; on a release PR it - # asserts the stamped section is exactly the fragments it consumed. + # changelog-assembled is available at 0.2.0 and later, not in + # 0.1.0. Adopt this step with the pin bump to 0.2.0 or later; + # never mix refs. Green NOTICE on every non-release PR; on a + # release PR it asserts the stamped section is exactly the + # fragments it consumed. - uses: heavy-duty/ceremony/actions/changelog-assembled@ - uses: heavy-duty/ceremony/actions/drill-recorded@ - # Unreleased: runner-isolated is not in 0.1.0. Adopt this step with - # the pin bump to the first tag that carries it; never mix refs. + # runner-isolated is available at 0.2.0 and later, not in 0.1.0. + # Adopt this step with the pin bump to 0.2.0 or later; never mix + # refs. - uses: heavy-duty/ceremony/actions/runner-isolated@ ``` @@ -112,7 +114,11 @@ the machinery at all: somebody adds one. This guide documents `main`. New machinery is marked **unreleased** - here until a release tag ships it. If an action does not exist at the + here until a release tag ships it — and the release PR that ships the + machinery clears, in that same PR, every marker its own assembled + section makes false: the section cites its issues, each marker cites + the same issue, and the release PR's diff is the one place both + halves are visible at once (#221). If an action does not exist at the consumer's pinned tag, adopt it with the pin bump to the first tag that carries it; never mix a moving or newer ref into an otherwise exact-pin consumer. In particular, `0.1.0` carries `changelog-armed`, @@ -298,7 +304,7 @@ together at the same pin: The consumer keeps its path mapping in `.github/labeler.yml` and its review panel plus scope taxonomy in `.github/labels.conf`. -**Additive means additive** (unreleased — #130): the scope job's only label +**Additive means additive** (available at `0.3.0` and later — #130): the scope job's only label write is `POST /issues/{n}/labels`, which adds the derived scopes and removes nothing, so a label applied while the job runs survives it. Earlier tags used `actions/labeler@v5`, which — even under `sync-labels: false` — replaces the @@ -436,16 +442,16 @@ mint→`needs-triage` check and `closed` the blocker-closes→`ready` self-heal; the stub and ceremony's own caller stay byte-for-byte identical, the parity #144 established. -The two-caller split (ceremony#209) is **unreleased**. A consumer pinned to -`0.4.0` or earlier keeps the previous single-caller shape — the labels -caller carrying the cron, `workflow_dispatch`, and `actions: read` — and -adopts the split at the pin bump to the first tag carrying ceremony#209. -Never mix refs to adopt it early. +The two-caller split (ceremony#209) is available at `0.4.1` and later. A +consumer pinned to `0.4.0` or earlier keeps the previous single-caller +shape — the labels caller carrying the cron, `workflow_dispatch`, and +`actions: read` — and adopts the split at the pin bump to `0.4.1` or +later. Never mix refs to adopt it early. The migration is **one atomic PR** with exactly four edits — crew, the consumer whose displaced-check evidence drove #209 (crew#227, crew#250), -is the worked example; written here against `0.4.1` as the illustrative -first tag carrying the split: +is the worked example; written here against `0.4.1`, the first tag +carrying the split: 1. **Pin bump, every reference together** ([Version pinning](#version-pinning)): `0.4.0` → `0.4.1` in the labels caller's `uses:` line **and in every