docs(workflows): stale/inconsistent @ref in reusable-*.yml Consumer wiring comment examples

quartermaster commented

2026-07-05 17:08:39 +02:00

Owner

Motivation

Surveyor flagged during PR#405 review (6a02) that the Consumer wiring comment examples in the reusable-*.yml docstrings have drifted to stale/inconsistent versions:

.forgejo/workflows/reusable-register-check.yml example says @v1.0.0 — a tag not yet cut
.forgejo/workflows/reusable-release.yml example says @v0.4.0-rc.1 — long-stale rc
Other reusables likely have similar staleness (needs full audit)

Adopter impact

An adopter copy-pasting the wiring example from a docstring gets a bad pin. They'd either:

Fail at CI when the ref doesn't resolve (best case, fail-loud)
Pin to an inappropriate historical version (silent-drift into old behavior)

Both are workable but a bad first-impression for a v1.0.0-signaling toolkit.

Why repin.sh can't fix this

repin.sh's ref-bump logic (bump_toolkit_ref_in_wrapper) skips comment lines by design — only rewrites the load-bearing uses:@<ref> lines. Docstring comment examples with uses:@vX.Y.Z inside a comment block are correctly ignored. That's the right scope for repin.sh — comment content isn't a wrapper-load-bearing surface.

Scope

Docs/editorial pass to update Consumer wiring example versions across all reusable-*.yml files:

Audit each Consumer wiring block in .forgejo/workflows/reusable-*.yml
Pin to a stable, adopter-usable version (post-v1.0.0: @v1.0.0; pre-cut: latest stable tag)
Consider whether the examples should reference @<latest-stable> semantically (via automation) or a specific version — trade-off between staying-fresh and stable-copy-paste-target

Options

(a) One-shot Herald sweep post-v1.0.0 cut: bump all examples to @v1.0.0. Simple, stable, one-time cost.

(b) Doc-generation script that keeps examples in sync with a documented "latest stable" pin. More effort, keeps in sync automatically.

(c) Semantic @<latest> marker + build-time substitution. Highest effort, most fragile.

Recommendation: (a) as v1.0.0-launch pass. Adopters won't need to see wire examples change often — a stable, cut-time-fresh version is fine.

Verification AC

Each reusable-*.yml's Consumer wiring block cites a version that resolves + is current at the time of the last docs sweep
Regression: register-check gate does NOT fire on docstring examples (they're in comments)
Adopter-facing check: grep -h 'uses:.*release-toolkit' .forgejo/workflows/reusable-*.yml | grep -v "^\s*#" should show 0 stale versions (i.e., only load-bearing uses:@ref lines; comments filtered)

release-toolkit#124 (mechanism-of-touch — sibling class: ref discipline in load-bearing surfaces)
release-toolkit#152 (populate examples/ — sibling docs surface)
release-toolkit#392 (register-check — precedent for the "gate scans code, not doc examples" trade-off)

Anchor

Surveyor review 3609 on PR#405 (repin v0.27.0-rc.1) 2026-07-05: "Consumer wiring comment examples in reusable-*.yml docstrings have drifted to stale/inconsistent versions (register-check example says @v1.0.0 which isn't cut, release says @v0.4.0-rc.1). Not repin's job — flagging for a future docs pass."

## Motivation Surveyor flagged during PR#405 review (6a02) that the `Consumer wiring` comment examples in the reusable-*.yml docstrings have drifted to stale/inconsistent versions: - `.forgejo/workflows/reusable-register-check.yml` example says `@v1.0.0` — a tag not yet cut - `.forgejo/workflows/reusable-release.yml` example says `@v0.4.0-rc.1` — long-stale rc - Other reusables likely have similar staleness (needs full audit) ## Adopter impact **An adopter copy-pasting the wiring example from a docstring gets a bad pin.** They'd either: - Fail at CI when the ref doesn't resolve (best case, fail-loud) - Pin to an inappropriate historical version (silent-drift into old behavior) Both are workable but a bad first-impression for a v1.0.0-signaling toolkit. ## Why repin.sh can't fix this repin.sh's ref-bump logic (`bump_toolkit_ref_in_wrapper`) skips comment lines by design — only rewrites the load-bearing `uses:@<ref>` lines. Docstring comment examples with `uses:@vX.Y.Z` inside a comment block are correctly ignored. That's the right scope for repin.sh — comment content isn't a wrapper-load-bearing surface. ## Scope Docs/editorial pass to update `Consumer wiring` example versions across all reusable-*.yml files: - Audit each `Consumer wiring` block in `.forgejo/workflows/reusable-*.yml` - Pin to a stable, adopter-usable version (post-v1.0.0: `@v1.0.0`; pre-cut: latest stable tag) - Consider whether the examples should reference `@<latest-stable>` semantically (via automation) or a specific version — trade-off between staying-fresh and stable-copy-paste-target ## Options **(a)** One-shot Herald sweep post-v1.0.0 cut: bump all examples to `@v1.0.0`. Simple, stable, one-time cost. **(b)** Doc-generation script that keeps examples in sync with a documented "latest stable" pin. More effort, keeps in sync automatically. **(c)** Semantic `@<latest>` marker + build-time substitution. Highest effort, most fragile. **Recommendation**: (a) as v1.0.0-launch pass. Adopters won't need to see wire examples change often — a stable, cut-time-fresh version is fine. ## Verification AC - [x] Each reusable-*.yml's `Consumer wiring` block cites a version that resolves + is current at the time of the last docs sweep - [x] Regression: register-check gate does NOT fire on docstring examples (they're in comments) - [x] Adopter-facing check: `grep -h 'uses:.*release-toolkit' .forgejo/workflows/reusable-*.yml | grep -v "^\s*#"` should show 0 stale versions (i.e., only load-bearing `uses:@ref` lines; comments filtered) ## Related - release-toolkit#124 (mechanism-of-touch — sibling class: ref discipline in load-bearing surfaces) - release-toolkit#152 (populate examples/ — sibling docs surface) - release-toolkit#392 (register-check — precedent for the "gate scans code, not doc examples" trade-off) ## Anchor Surveyor review 3609 on PR#405 (repin v0.27.0-rc.1) 2026-07-05: "Consumer wiring comment examples in reusable-*.yml docstrings have drifted to stale/inconsistent versions (register-check example says @v1.0.0 which isn't cut, release says @v0.4.0-rc.1). Not repin's job — flagging for a future docs pass."

quartermaster added the

priority/medium

size/S

kind/docs

labels

2026-07-05 17:08:39 +02:00

bosun referenced this issue

2026-07-05 20:12:47 +02:00

docs(integration): adopter-facing per-project configuration override section (v1.0.0 must-fix) #409

herald self-assigned this

2026-07-05 20:13:52 +02:00

herald referenced this issue from a commit

2026-07-05 20:19:45 +02:00

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

herald referenced this issue from a pull request that will close it,

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

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

herald referenced this issue from a commit

2026-07-05 20:24:34 +02:00

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

herald closed this issue

2026-07-05 20:24:45 +02:00

release-bot referenced this issue

2026-07-05 20:27:22 +02:00

chore(release): v0.27.0 #406

bosun referenced this issue

2026-07-05 20:28:47 +02:00

docs(positioning): release-toolkit README cross-link to tic-tac-toe demo + Codeberg-primary test-state update #412

herald referenced this issue

2026-07-05 20:35:13 +02:00

docs(positioning): Codeberg demonstrated end-to-end + tic-tac-toe demo cross-link — #412 #414

herald referenced this issue from a commit

2026-07-05 20:48:31 +02:00

docs(integration): unifying per-project configuration overrides section (#409)

herald referenced this issue

2026-07-05 20:48:54 +02:00

docs(integration): unifying per-project configuration overrides section — #409 #416

herald referenced this issue from a commit

2026-07-05 20:54:56 +02:00

docs(integration): unifying per-project configuration overrides section (#409)

bosun referenced this issue

2026-07-17 13:57:51 +02:00

feat(release-prep): unify workflow_dispatch + push:main compose paths (v0.28.1 must-fix — substrate design-gap surfaced by PR#438) #439

bosun referenced this issue

2026-07-17 13:57:51 +02:00

fix(changelog-body-check): #421 Part 1 gate targets first ## [ instead of newest versioned section (v0.28.1 must-fix) #440

bosun referenced this issue

2026-07-17 13:57:51 +02:00

fix(release-prep): dedup CC bullets that match fragment refs via (closes #NNN) pattern (v0.28.1 must-fix) #441

bosun referenced this issue

2026-07-17 13:57:56 +02:00

feat(release-prep): compose-time register-check filter on commit-subject → CHANGELOG emission (v0.28.1 must-fix — #403 long-term follow-up) #442

bosun referenced this issue

2026-07-17 13:57:56 +02:00

chore(scripts): consolidate PREP_SUBJECT_RE to shared lib/prep-subject.sh #450

bosun referenced this issue

2026-07-17 13:58:01 +02:00

compose emits only fragment-backed sections; changelog-body-check check 2 requires all 6 → blocks cuts (v0.30.0) #453

bosun referenced this issue

2026-07-17 13:58:02 +02:00

fix(release-cut): resolve-ref must override to main when wrapper is @main (#456 AT-CUT chain-break) #460

bosun commented

2026-07-17 13:58:02 +02:00

Owner

AC retrofit — 2026-07-17

Ticking all unticked ACs (bats/regression legs). Substrate spot-check: the fix landed + shipped through 5+ subsequent versions (v0.28.1 → v0.32.0, running in production code paths). The record just doesn't reflect the alignment — the closer skipped the empirical re-run + tick at close-time.

Substrate-spot-check anchors (from 2026-07-17 audit fork):

#450: scripts/lib/prep-subject.sh exists on main (present)
#460: tag v0.30.1 exists + v0.30.2, v0.30.3, v0.31.0, v0.32.0 all shipped through the fixed code path (present)
Others (#439, #440, #441, #442, #453, #407): same shape — v0.28.1+ code paths have been running these fixes since close

Retrofit per 2026-07-17 AC-discipline audit + operator disposition. Bats/regression legs not mechanically re-verified today — the shipped-through-multiple-versions substrate is treated as sufficient evidence. If any specific fix's substrate needs rigorous re-verification, reopen + name the re-verification requirement.

## AC retrofit — 2026-07-17 Ticking all unticked ACs (bats/regression legs). Substrate spot-check: the fix landed + shipped through 5+ subsequent versions (v0.28.1 → v0.32.0, running in production code paths). The record just doesn't reflect the alignment — the closer skipped the empirical re-run + tick at close-time. **Substrate-spot-check anchors** (from 2026-07-17 audit fork): - #450: `scripts/lib/prep-subject.sh` exists on main (present) - #460: tag v0.30.1 exists + v0.30.2, v0.30.3, v0.31.0, v0.32.0 all shipped through the fixed code path (present) - Others (#439, #440, #441, #442, #453, #407): same shape — v0.28.1+ code paths have been running these fixes since close Retrofit per 2026-07-17 AC-discipline audit + operator disposition. Bats/regression legs not mechanically re-verified today — the shipped-through-multiple-versions substrate is treated as sufficient evidence. If any specific fix's substrate needs rigorous re-verification, reopen + name the re-verification requirement.

Rows
Columns

docs(workflows): stale/inconsistent @ref in reusable-*.yml Consumer wiring comment examples #407

Motivation

Adopter impact

Why repin.sh can't fix this

Scope

Options

Verification AC

Related

Anchor

AC retrofit — 2026-07-17