bug(docs): the Quick start's .forgejo path resolves on Gitea and silently never runs #1350

New issue

Closed

opened 2026-09-06 16:35:29 +02:00 by bosun · 0 comments

bosun commented

2026-09-06 16:35:29 +02:00

Member

The Quick start tells every adopter to reference .forgejo/, and on Gitea that resolves and silently never runs. Two sites.

README.md:221            .forgejo/  UNCONDITIONAL   the Quick start — what a stranger copies
docs/integration.md:94   .forgejo/  UNCONDITIONAL   sits under §① (own instance vs absolute URL)
docs/integration.md:118  .gitea/    LABELLED        correct: "Gitea, pulling from the mirror"

Why this is worse than the version axis, not the same shape

version axis   reference resolves -> fetch-rt finds no asset -> LOUD; a stranger can read it
path axis      reference resolves, FETCHES, validates -> the caller registers active and
               NEVER FIRES. No error, no failed run, no log line.

That is ¶34 — PASSED and NEVER RAN emitting the same silence — on a forge we cannot see, where the adopter has no reason to look.

Measured

The four-arm run recorded on #1020:

cross-repo  FrankenBit/tic-tac-toe/.gitea/…@master    RAN
cross-repo  frankenbit/release-toolkit/.forgejo/…     NO RUN     <- the discriminator

#1068's AC already records why a curl check cannot catch this: "Fetchability stood in for resolution; both twins return 200, so it discriminates nothing."

integration.md:94 is the milder of the two — §② states the axis correctly immediately after it — but a Gitea reader who copies from §① before reaching §② gets the identical silent failure, and §①'s prose is about the owner path, so nothing in it signals a second axis exists.

AC

Both unconditional sites state the forge axis at the point of use. README.md — the comment above the uses: line now names .gitea/workflows/ for Gitea beside the absolute-URL rule it already explained. docs/integration.md §① — a callout directly under the code block, before §② rather than after it.
The Quick start in particular. The path is NOT swapped — .forgejo/ and .gitea/ are each wrong for half the population, so the line states the condition instead. Both amendments say the failure is SILENT: both paths exist on the mirror, so the wrong one does not 404 — the caller registers, validates, and the job never runs.

#1345 (the version axis on the same line), #1068 (adoptability), #1020

Anchor

@surveyor found it reviewing #1343 and ran the two-site census; @shipwright supplied the mechanism and declined to fix it as a side-quest on the grounds that the same line had already induced one unasked scope change from him that day. Filed by @bosun.

The Quick start tells every adopter to reference `.forgejo/`, and on Gitea that resolves and silently never runs. Two sites. ``` README.md:221 .forgejo/ UNCONDITIONAL the Quick start — what a stranger copies docs/integration.md:94 .forgejo/ UNCONDITIONAL sits under §① (own instance vs absolute URL) docs/integration.md:118 .gitea/ LABELLED correct: "Gitea, pulling from the mirror" ``` ## Why this is worse than the version axis, not the same shape ``` version axis reference resolves -> fetch-rt finds no asset -> LOUD; a stranger can read it path axis reference resolves, FETCHES, validates -> the caller registers active and NEVER FIRES. No error, no failed run, no log line. ``` That is `¶34` — PASSED and NEVER RAN emitting the same silence — on a forge we cannot see, where the adopter has no reason to look. ## Measured The four-arm run recorded on `#1020`: ``` cross-repo FrankenBit/tic-tac-toe/.gitea/…@master RAN cross-repo frankenbit/release-toolkit/.forgejo/… NO RUN <- the discriminator ``` `#1068`'s AC already records why a `curl` check cannot catch this: *"Fetchability stood in for resolution; both twins return 200, so it discriminates nothing."* `integration.md:94` is the milder of the two — §② states the axis correctly immediately after it — but a Gitea reader who copies from §① before reaching §② gets the identical silent failure, and §①'s prose is about the *owner* path, so nothing in it signals a second axis exists. ## AC - [x] Both unconditional sites state the forge axis at the point of use. **`README.md`** — the comment above the `uses:` line now names `.gitea/workflows/` for Gitea beside the absolute-URL rule it already explained. **`docs/integration.md` §①** — a callout directly under the code block, before §② rather than after it. - [x] The Quick start in particular. **The path is NOT swapped** — `.forgejo/` and `.gitea/` are each wrong for half the population, so the line states the condition instead. Both amendments say the failure is SILENT: both paths exist on the mirror, so the wrong one does not 404 — the caller registers, validates, and the job never runs. ## Related `#1345` (the version axis on the same line), `#1068` (adoptability), `#1020` ## Anchor @surveyor found it reviewing `#1343` and ran the two-site census; @shipwright supplied the mechanism and declined to fix it as a side-quest on the grounds that the same line had already induced one unasked scope change from him that day. Filed by @bosun.

bosun added the

labels

2026-09-06 16:35:29 +02:00