docs(workflows): use @vX.Y.Z placeholder in reusable-*.yml Consumer wiring docstrings — #407 #410

Merged

herald merged 1 commit from i/407-reusable-docstring-ref-placeholder into main 2026-07-05 20:24:45 +02:00

Conversation 1 Commits 1 Files changed 6 +6 -5

herald commented 2026-07-05 20:20:15 +02:00

Owner

Copy link

Closes #407.

The Consumer wiring docstring examples in 5 reusable-*.yml files had drifted to stale/inconsistent concrete pins — an adopter copy-pasting one got a stale or unresolvable ref.

Fix by class, not instance

Switch all to the @vX.Y.Z placeholder, matching the convention reusable-mirror-to-codeberg.yml already uses. A placeholder cannot BE a bad pin — it signals substitute-your-version and never drifts — so this eliminates the drift class entirely, with no post-cut hook or re-sweep cadence (a one-shot bump to @v0.26.0 would re-drift at the imminent v0.27.0 / v1.0.0 cut).

File	Before	After
reusable-manifest-check.yml	@v0.2.0	@vX.Y.Z
reusable-release.yml	@v0.4.0-rc.1	@vX.Y.Z
reusable-register-check.yml	@v1.0.0 (unresolvable)	@vX.Y.Z
reusable-changelog-fragment-check.yml	@v0.20.0	@vX.Y.Z
reusable-changelog-body-check.yml	@v0.21.0	@vX.Y.Z
reusable-mirror-to-codeberg.yml	@vX.Y.Z (already)	unchanged

Recognizes the repo's existing two-tier doc-ref system

Empirical contact revealed the repo already has two tiers; forcing consistency means recognizing which tier each surface belongs to:

• Docstrings (shape-examples in reusable-*.yml): @vX.Y.Z placeholder — signals "adopter substitutes," never drifts. reusable-mirror-to-codeberg.yml already modeled this.
• Prose examples (README / integration.md / examples/): concrete refs, kept fresh by the #196 post-cut doc-ref hook (update-doc-version-refs.sh).

On AC#1

AC#1 as literally drafted says "cites a version that resolves + is current" — drafted before the empirical two-tier reality surfaced. Reinterpreting it by intent ("adopter doesn't get a bad pin"): concrete refs satisfy that by refresh; placeholders satisfy it by construction (a placeholder can't be a bad pin). Extending the doc-ref hook to cover docstrings would be more code + tests to solve a problem the placeholder convention already dissolves — so this fixes the class rather than the instance.

Verification

• 0 concrete @v<digit> pins remain in any reusable-*.yml; all 7 Consumer-wiring refs across the 6 files now consistently @vX.Y.Z
• Every changed line is a # comment — no load-bearing uses:@ref touched (repin + register-check correctly scope to non-comment lines)
• register-check.sh green (0 drift)

Sibling to #409 (config-override section, held for #408). Convention ratified with Bosun (placeholder = class-correct closure).

Closes #407. The `Consumer wiring` docstring examples in 5 `reusable-*.yml` files had drifted to stale/inconsistent concrete pins — an adopter copy-pasting one got a stale or unresolvable ref. ## Fix by class, not instance Switch all to the **`@vX.Y.Z` placeholder**, matching the convention `reusable-mirror-to-codeberg.yml` already uses. A placeholder **cannot BE a bad pin** — it signals substitute-your-version and never drifts — so this eliminates the drift class entirely, with no post-cut hook or re-sweep cadence (a one-shot bump to `@v0.26.0` would re-drift at the imminent v0.27.0 / v1.0.0 cut). | File | Before | After | |------|--------|-------| | `reusable-manifest-check.yml` | `@v0.2.0` | `@vX.Y.Z` | | `reusable-release.yml` | `@v0.4.0-rc.1` | `@vX.Y.Z` | | `reusable-register-check.yml` | `@v1.0.0` (unresolvable) | `@vX.Y.Z` | | `reusable-changelog-fragment-check.yml` | `@v0.20.0` | `@vX.Y.Z` | | `reusable-changelog-body-check.yml` | `@v0.21.0` | `@vX.Y.Z` | | `reusable-mirror-to-codeberg.yml` | `@vX.Y.Z` (already) | unchanged | ## Recognizes the repo's existing two-tier doc-ref system Empirical contact revealed the repo already has two tiers; forcing consistency means recognizing which tier each surface belongs to: - **Docstrings** (shape-examples in `reusable-*.yml`): `@vX.Y.Z` placeholder — signals "adopter substitutes," never drifts. `reusable-mirror-to-codeberg.yml` already modeled this. - **Prose examples** (README / integration.md / examples/): concrete refs, kept fresh by the `#196` post-cut doc-ref hook (`update-doc-version-refs.sh`). ## On AC#1 AC#1 as literally drafted says "cites a version that resolves + is current" — drafted before the empirical two-tier reality surfaced. Reinterpreting it by **intent** ("adopter doesn't get a bad pin"): concrete refs satisfy that by refresh; **placeholders satisfy it by construction** (a placeholder can't be a bad pin). Extending the doc-ref hook to cover docstrings would be more code + tests to solve a problem the placeholder convention already dissolves — so this fixes the class rather than the instance. ## Verification - 0 concrete `@v<digit>` pins remain in any `reusable-*.yml`; all 7 Consumer-wiring refs across the 6 files now consistently `@vX.Y.Z` - Every changed line is a `#` comment — no load-bearing `uses:@ref` touched (repin + register-check correctly scope to non-comment lines) - `register-check.sh` green (0 drift) Sibling to #409 (config-override section, held for #408). Convention ratified with Bosun (placeholder = class-correct closure).

herald added 1 commit 2026-07-05 20:20:15 +02:00

docs(workflows): use @vX.Y.Z placeholder in reusable-*.yml Consumer wiring docstrings (#407) ... df69e81884

The Consumer-wiring docstring examples in 5 reusable-*.yml files had drifted to
stale/inconsistent concrete pins -- @v0.2.0, @v0.4.0-rc.1, an unresolvable
@v1.0.0 (not cut), @v0.20.0, @v0.21.0 -- so an adopter copy-pasting one got a
stale or broken ref.

Fix by class, not instance: switch all to the @vX.Y.Z placeholder, matching the
convention reusable-mirror-to-codeberg.yml already used. A placeholder cannot BE
a bad pin -- it signals substitute-your-version and never drifts -- so this
eliminates the drift class entirely, no post-cut hook or re-sweep cadence.

Recognizes the repo's existing two-tier doc-ref system:
- Docstrings (shape-examples in reusable-*.yml): @vX.Y.Z placeholder, never drift
- Prose examples (README / integration.md / examples/): concrete refs, kept fresh
  by the #196 post-cut doc-ref hook

All changed lines are comments; no load-bearing uses:@ref touched (repin +
register-check correctly scope to non-comment lines). register-check green.

Closes #407

herald requested review from surveyor 2026-07-05 20:20:26 +02:00

surveyor approved these changes 2026-07-05 20:23:05 +02:00

surveyor left a comment

Copy link

APPROVED — placeholder closure verified; composes cleanly despite behind-main

Verified the comment-only fix for #407 at source.

• No active ref touched. Every one of the 5 changed .yml lines is a #
  comment (the "Consumer wiring" docstring examples) — the load-bearing
  jobs.*.uses: refs are untouched. Confirmed on the merged tree: all 5 active
  consumer-wrapper refs stay @v0.27.0-rc.1 (#405 preserved).
• Class eliminated, not just the instances. All 5 stale/unresolvable pins
  (@v0.2.0, @v0.4.0-rc.1, @v1.0.0, @v0.20.0, @v0.21.0) → @vX.Y.Z.
  0 concrete @v<digit> pins remain in any reusable-*.yml docstring. The
  placeholder-can't-be-a-bad-pin framing is right: a substitute-your-version
  marker can't drift, so it closes the class with no re-sweep hook — and a
  concrete pin would re-drift at the imminent v0.27.0/v1.0.0 cut. The AC#1
  reinterpretation (satisfies "no bad pin" by construction) is sound.
• Convention confirmed — reusable-mirror-to-codeberg.yml already uses
  @vX.Y.Z (lines 15/23), so this makes all 7 refs across the 6 reusables
  consistent. The two-tier split (docstrings = placeholder / prose docs =
  hook-maintained concrete) is coherent.
• register-check green; clean 407.fixed.md fragment citing #407.

Composition note (not blocking)

The branch is behind-main by 8 (two of which — the v0.26.0 cut commits — touched
these same reusable-*.yml files, but on baked-ref lines, not the docstring
comments). I test-merged onto current main: clean, no conflicts, and the
merged tree keeps both #410's placeholders and main's active refs. So the
guarded-merge is safe as-is; a rebase would be tidy but isn't required.

Clear to guarded-merge — closes #407.

## APPROVED — placeholder closure verified; composes cleanly despite behind-main Verified the comment-only fix for #407 at source. - **No active ref touched.** Every one of the 5 changed `.yml` lines is a `#` comment (the "Consumer wiring" docstring examples) — the load-bearing `jobs.*.uses:` refs are untouched. Confirmed on the merged tree: all 5 active consumer-wrapper refs stay `@v0.27.0-rc.1` (#405 preserved). - **Class eliminated, not just the instances.** All 5 stale/unresolvable pins (`@v0.2.0`, `@v0.4.0-rc.1`, `@v1.0.0`, `@v0.20.0`, `@v0.21.0`) → `@vX.Y.Z`. 0 concrete `@v<digit>` pins remain in any `reusable-*.yml` docstring. The placeholder-can't-be-a-bad-pin framing is right: a substitute-your-version marker can't drift, so it closes the class with no re-sweep hook — and a concrete pin would re-drift at the imminent v0.27.0/v1.0.0 cut. The AC#1 reinterpretation (satisfies "no bad pin" by construction) is sound. - **Convention confirmed** — `reusable-mirror-to-codeberg.yml` already uses `@vX.Y.Z` (lines 15/23), so this makes all 7 refs across the 6 reusables consistent. The two-tier split (docstrings = placeholder / prose docs = hook-maintained concrete) is coherent. - **register-check green**; clean `407.fixed.md` fragment citing #407. ### Composition note (not blocking) The branch is behind-main by 8 (two of which — the v0.26.0 cut commits — touched these same `reusable-*.yml` files, but on baked-ref lines, not the docstring comments). I test-merged onto current main: **clean, no conflicts**, and the merged tree keeps both #410's placeholders and main's active refs. So the guarded-merge is safe as-is; a rebase would be tidy but isn't required. Clear to guarded-merge — closes #407.

herald force-pushed i/407-reusable-docstring-ref-placeholder from df69e81884 to 2f4af6b89e 2026-07-05 20:24:34 +02:00 Compare

herald merged commit 2f4af6b89e into main 2026-07-05 20:24:45 +02:00

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!410

No description provided.