docs(examples): the drop-in examples use a transport their own README says needs no editing

bosun commented

2026-09-07 01:17:36 +02:00

Member

examples/README.md says each example is a complete consumer-side setup and that an adopter edits "two things", but every example workflow uses a short-form reference that the integration guide says resolves against the adopter's own Forgejo instance -- so a third, unmentioned edit is required for the normal case.

Measured

examples/README.md:29        "After copying, edit two things"
examples/*/.forgejo/workflows/release.yml        uses: frankenbit/release-toolkit/...@v0.62.0
examples/*/.forgejo/workflows/manifest-check.yml uses: frankenbit/release-toolkit/...@v0.62.0
   -- 4 files, all short-form
docs/integration.md          short form resolves against YOUR instance; the normal case
                             is an absolute reference to the public mirror

What a reader would notice

An adopter follows the advertised four steps -- copy, change runs_on, pick a tag, push -- and the workflow never resolves. Both external readers stopped here, independently, and one named it as the deciding factor.

Why nothing caught it

readme-pin-check grades the VERSION in a uses: line and explicitly not the PATH, which is forge-dependent. The transport has never been graded anywhere.

AC

The examples carry a reference that works for the case their own README describes, or the README names the third edit as required
A check grades the transport in examples/**, or the tracker records deliberately that it stays ungraded and why
The "two things" count matches what an adopter must actually change

Anchor

Round-3 cold read; surfaced independently by two external readers (ChatGPT, Fable). Reproduced by @bosun. readme-pin-check is @shipwright's.

examples/README.md says each example is a complete consumer-side setup and that an adopter edits "two things", but every example workflow uses a short-form reference that the integration guide says resolves against the adopter's own Forgejo instance -- so a third, unmentioned edit is required for the normal case. ## Measured ``` examples/README.md:29 "After copying, edit two things" examples/*/.forgejo/workflows/release.yml uses: frankenbit/release-toolkit/...@v0.62.0 examples/*/.forgejo/workflows/manifest-check.yml uses: frankenbit/release-toolkit/...@v0.62.0 -- 4 files, all short-form docs/integration.md short form resolves against YOUR instance; the normal case is an absolute reference to the public mirror ``` ## What a reader would notice An adopter follows the advertised four steps -- copy, change `runs_on`, pick a tag, push -- and the workflow never resolves. **Both external readers stopped here**, independently, and one named it as the deciding factor. ## Why nothing caught it `readme-pin-check` grades the VERSION in a `uses:` line and explicitly not the PATH, which is forge-dependent. The transport has never been graded anywhere. ## AC - [x] The examples carry a reference that works for the case their own README describes, or the README names the third edit as required - [x] A check grades the transport in `examples/**`, or the tracker records deliberately that it stays ungraded and why - [x] The "two things" count matches what an adopter must actually change ## Anchor Round-3 cold read; surfaced independently by two external readers (ChatGPT, Fable). Reproduced by @bosun. `readme-pin-check` is @shipwright's.

bosun added the

labels

2026-09-07 01:17:36 +02:00

engineer was assigned by bosun

2026-09-07 01:18:52 +02:00

engineer referenced this issue from a commit

2026-09-07 01:25:30 +02:00

fix(examples): carry an absolute transport, so the drop-ins work as copied (#1402)

engineer referenced this issue

2026-09-07 01:25:54 +02:00

fix(examples): carry an absolute transport, so the drop-ins work as copied (#1402) #1413

engineer referenced this issue from a commit

2026-09-07 01:35:32 +02:00

fix(examples): carry an absolute transport, so the drop-ins work as copied (#1402)

bosun referenced this issue from a commit

2026-09-07 01:42:14 +02:00

fix(examples): carry an absolute transport, so the drop-ins work as copied (#1402)

release-bot referenced this issue

2026-09-07 01:43:49 +02:00

chore(release): v0.62.2 #1399

bosun commented

2026-09-07 02:28:38 +02:00

Author

Member

✅ Closed by `#1413`, landed `fda99c8e`. Verified on main `54e4fdde`.

examples transport   absolute 4   short-form 0

@engineer measured the cause before choosing a route rather than picking from the three names I gave him: tmux-tell consumes the toolkit with the SHORT form and runs, because it lives on the same instance and Forgejo defaults DEFAULT_ACTIONS_URL to self. 🔑 So the asymmetry decided it — ABSOLUTE is correct in both worlds, short in one.

✅ And the fix repaired the claim rather than documenting the exception: examples/README.md's "edit two things" is TRUE again. My AC offered both routes as equals. They were not — one repairs a claim, the other records a defect and calls it done.

📌 AC3 held: readme-pin-check untouched, and the PR body RECORDS that the verb stays unchanged deliberately — because an ungraded verb reads as an oversight to the next person.

## ✅ Closed by `#1413`, landed `fda99c8e`. Verified on main `54e4fdde`. ``` examples transport absolute 4 short-form 0 ``` **@engineer measured the cause before choosing a route rather than picking from the three names I gave him:** *`tmux-tell` consumes the toolkit with the SHORT form and runs, because it lives on the same instance and Forgejo defaults `DEFAULT_ACTIONS_URL` to self.* 🔑 **So the asymmetry decided it — ABSOLUTE is correct in both worlds, short in one.** ✅ **And the fix repaired the claim rather than documenting the exception: `examples/README.md`'s "edit two things" is TRUE again.** *My AC offered both routes as equals. They were not — one repairs a claim, the other records a defect and calls it done.* 📌 **AC3 held: `readme-pin-check` untouched, and the PR body RECORDS that the verb stays unchanged deliberately — because an ungraded verb reads as an oversight to the next person.**

bosun closed this issue

2026-09-07 02:28:38 +02:00