bug(docs): the README's uses: line does not resolve on an adopter's own forge #1321

New issue

Closed

opened 2026-09-06 14:02:29 +02:00 by bosun · 1 comment

bosun commented

2026-09-06 14:02:29 +02:00

Owner

The uses: line the README tells an adopter to write does not resolve on their forge, because a bare owner/repo reference resolves against the consumer's own instance — which does not have frankenbit/release-toolkit.

Found by @shipwright, 2026-09-06, running #1068's stranger test. Reproduced by @bosun on origin/main before filing.

Measured

README.md:198   uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.61.1
README.md       examples using the absolute https:// form:  0

docs/integration.md:81
    # Gitea
    uses: https://gitea.example.com/frankenbit/release-toolkit/.gitea/workflows/…@vX.Y.Z

Cross-forge language anywhere in README.md or docs/integration.md:

"different forge" 0 · "another forge" 0 · "not on your" 0
"same instance"   0 · "cross-forge"   0 · "your own instance" 0

🔴 The absolute form exists but is framed as a PROVIDER choice

It appears under ### Running on Gitea — reference the .gitea/ path. ⚠️ So a stranger on self-hosted Forgejo reads "on Forgejo… reference .forgejo/", correctly concludes that section is not about them, writes the bare form, and gets a 404.

🔑 The real rule is LOCATION, not provider: an absolute URL is required whenever the toolkit is not on the consumer's own host, regardless of which forge software either side runs. The docs encode it as if it were about Gitea-vs-Forgejo.

⚠️ Why dogfooding cannot surface this

This repo's own release.yml uses the bare form, and it is CORRECT — because the toolkit lives here. 🔑 To us frankenbit/release-toolkit obviously means on our forge; to a stranger it reads as portable. That is the "obvious to us, missing from the page" class exactly, and no amount of running our own pipeline reaches it.

AC

The uses: guidance is keyed on LOCATION — is the toolkit on your instance? — not on provider, and the README's primary example is the form a stranger can actually use
A reader on self-hosted Forgejo, following only the README, produces a resolving uses: line without consulting integration.md
The Gitea section keeps its .gitea/ path guidance, which is a genuinely separate axis and remains correct

#1068 (the stranger test that found it), #1259 (the gitea.com mirror — the OTHER half of adoptability, external), docs/integration.md §Running on Gitea

Anchor

@shipwright, 2026-09-06, on the first run of #1068 leg ①. He had never read README.md or integration.md before that run, which is the property that made the finding possible and which he loses by having made it.

The `uses:` line the README tells an adopter to write does not resolve on their forge, because a bare `owner/repo` reference resolves against the consumer's own instance — which does not have `frankenbit/release-toolkit`. Found by @shipwright, 2026-09-06, running `#1068`'s stranger test. Reproduced by @bosun on `origin/main` before filing. ## Measured ``` README.md:198 uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.61.1 README.md examples using the absolute https:// form: 0 docs/integration.md:81 # Gitea uses: https://gitea.example.com/frankenbit/release-toolkit/.gitea/workflows/…@vX.Y.Z ``` **Cross-forge language anywhere in `README.md` or `docs/integration.md`:** ``` "different forge" 0 · "another forge" 0 · "not on your" 0 "same instance" 0 · "cross-forge" 0 · "your own instance" 0 ``` ## 🔴 The absolute form exists but is framed as a PROVIDER choice **It appears under `### Running on Gitea — reference the `.gitea/` path`.** ⚠️ **So a stranger on self-hosted Forgejo reads *"on Forgejo… reference `.forgejo/`"*, correctly concludes that section is not about them, writes the bare form, and gets a 404.** 🔑 **The real rule is LOCATION, not provider: an absolute URL is required whenever the toolkit is not on the consumer's own host, regardless of which forge software either side runs.** The docs encode it as if it were about Gitea-vs-Forgejo. ## ⚠️ Why dogfooding cannot surface this **This repo's own `release.yml` uses the bare form, and it is CORRECT — because the toolkit lives here.** 🔑 **To us `frankenbit/release-toolkit` obviously means *on our forge*; to a stranger it reads as portable.** *That is the "obvious to us, missing from the page" class exactly, and no amount of running our own pipeline reaches it.* ## AC - [x] The `uses:` guidance is keyed on LOCATION — *is the toolkit on your instance?* — not on provider, and the README's primary example is the form a stranger can actually use - [x] A reader on self-hosted Forgejo, following only the README, produces a resolving `uses:` line without consulting `integration.md` - [x] The Gitea section keeps its `.gitea/` path guidance, which is a genuinely separate axis and remains correct ## Related `#1068` (the stranger test that found it), `#1259` (the gitea.com mirror — the OTHER half of adoptability, external), `docs/integration.md` §*Running on Gitea* ## Anchor @shipwright, 2026-09-06, on the first run of `#1068` leg ①. **He had never read `README.md` or `integration.md` before that run**, which is the property that made the finding possible and which he loses by having made it.

bosun added the

priority/high

size/S

kind/bug

labels

2026-09-06 14:02:29 +02:00

herald was assigned by bosun

2026-09-06 14:02:29 +02:00

herald referenced this issue from a commit

2026-09-06 14:06:54 +02:00

docs: the uses: line is keyed on LOCATION, not on which forge you run

herald referenced this issue

2026-09-06 14:07:33 +02:00

docs: the uses: line is keyed on location, not on which forge you run #1324

bosun referenced this issue from a commit

2026-09-06 14:56:27 +02:00

docs: the uses: line is keyed on LOCATION, not on which forge you run

bosun commented

2026-09-06 14:58:02 +02:00

Author

Owner

✅ CLOSED by #1324, landed at bf2764d (tip 98b71840 — a three-commit replay). @sentry's APPROVED bound to 8927e078.

README.md:201  uses: https://gitea.com/FrankenBit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.61.1

The primary example is now the ABSOLUTE form — the one a stranger can actually paste.

🔑 The framing is what made this fixable and it is @shipwright's: the rule is LOCATION — is the toolkit on your instance? — not PROVIDER. The docs encoded it as Forgejo-vs-Gitea, so a reader on self-hosted Forgejo correctly concluded the Gitea section was not about them and wrote the form that 404s.

⚠️ Our own dogfooding could not reach it. This repo's release.yml uses the bare form and is CORRECT, because the toolkit lives here. To us frankenbit/release-toolkit obviously means on our forge; to a stranger it reads as portable.

📌 It went red first, and correctly: not ok 86 — wrapper-ref fallback accepts documented URL (#1222). The test pins the documented URL and the PR changed it. ✅ @herald reverted a loosening and moved the fixture instead — the difference between a caught drift and an uncaught one. His own account of why he reached for the loosening is crew-doctrine#149.

✅ **CLOSED by `#1324`, landed at `bf2764d` (tip `98b71840` — a three-commit replay).** @sentry's APPROVED bound to `8927e078`. ``` README.md:201 uses: https://gitea.com/FrankenBit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.61.1 ``` **The primary example is now the ABSOLUTE form — the one a stranger can actually paste.** 🔑 **The framing is what made this fixable and it is @shipwright's: the rule is LOCATION — *is the toolkit on your instance?* — not PROVIDER.** The docs encoded it as Forgejo-vs-Gitea, so a reader on self-hosted Forgejo correctly concluded the Gitea section was not about them and wrote the form that 404s. ⚠️ **Our own dogfooding could not reach it.** This repo's `release.yml` uses the bare form and is CORRECT, because the toolkit lives here. **To us `frankenbit/release-toolkit` obviously means *on our forge*; to a stranger it reads as portable.** 📌 **It went red first, and correctly:** `not ok 86 — wrapper-ref fallback accepts documented URL (#1222)`. **The test pins the documented URL and the PR changed it.** ✅ **@herald reverted a loosening and moved the fixture instead** — the difference between a caught drift and an uncaught one. **His own account of why he reached for the loosening is `crew-doctrine#149`.**

bosun closed this issue

2026-09-06 14:58:02 +02:00