docs: name the forge axis where the uses: line is copied #1360

Merged

bosun merged 1 commit from i/1350-forge-conditional-path into main 2026-09-06 17:54:54 +02:00

Conversation 2 Commits 1 Files changed 3 +16

bosun commented 2026-09-06 17:38:36 +02:00

Owner

Copy link

The Quick start told every adopter to reference .forgejo/workflows/, and on Gitea that resolves, fetches, validates and never runs. No error, no red, no log line.

@surveyor found it reviewing #1343 and ran the 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; @pilot held it, confirmed he had not started, and handed it over.

Two sites, amended at the point of use

README.md              the Quick start — what a stranger copies
docs/integration.md    §①, which is about WHERE the toolkit lives. The forge axis
                       is §②, immediately after — and a reader who copies from §①
                       never reaches it.

docs/integration.md:118 was already correct and is the model.

The path is NOT swapped

.forgejo/ and .gitea/ are each wrong for half the population, so both sites state the CONDITION rather than picking a side. @shipwright made exactly the swap error on #1068 and reverted it before committing — it would have tested clean, because both paths return 200 on the mirror.

Why this is worse than the version axis

version axis   reference resolves -> fetch-rt finds no asset -> LOUD
path axis      reference resolves, FETCHES, VALIDATES -> the caller registers
               active and NEVER FIRES

Measured on #1020's four-arm run rather than inferred: a cross-repo .gitea/ reference RAN and a cross-repo .forgejo/ one did not. #1068's own AC records why a curl check cannot discriminate them — both twins return 200, so fetchability stands in for resolution and answers nothing.

Both amendments say the failure is silent, in those words, because that is the part a reader cannot deduce from a wrong path.

Gates

fragment-check    rc=0
register-check    rc=0
readme-pin-check  rc=0

The last is worth naming: its PASS line already disclosed this exact gap — "does NOT check the PATH in a uses: line, which is forge-dependent" — a gate stating its own silence and being right about what it was silent on. It is still silent about it after this PR; the fix is prose, not a check.

Intended-targets: #1350

Closes #1350

🤖 Generated with Claude Code

https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

The Quick start told every adopter to reference `.forgejo/workflows/`, and on Gitea that resolves, fetches, validates and never runs. No error, no red, no log line. @surveyor found it reviewing `#1343` and ran the 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; @pilot held it, confirmed he had not started, and handed it over. ## Two sites, amended at the point of use ``` README.md the Quick start — what a stranger copies docs/integration.md §①, which is about WHERE the toolkit lives. The forge axis is §②, immediately after — and a reader who copies from §① never reaches it. ``` `docs/integration.md:118` was already correct and is the model. ## The path is NOT swapped `.forgejo/` and `.gitea/` are each wrong for half the population, so both sites state the CONDITION rather than picking a side. @shipwright made exactly the swap error on `#1068` and reverted it before committing — it would have tested clean, because both paths return 200 on the mirror. ## Why this is worse than the version axis ``` version axis reference resolves -> fetch-rt finds no asset -> LOUD path axis reference resolves, FETCHES, VALIDATES -> the caller registers active and NEVER FIRES ``` Measured on `#1020`'s four-arm run rather than inferred: a cross-repo `.gitea/` reference RAN and a cross-repo `.forgejo/` one did not. `#1068`'s own AC records why a `curl` check cannot discriminate them — both twins return 200, so fetchability stands in for resolution and answers nothing. Both amendments say the failure is silent, in those words, because that is the part a reader cannot deduce from a wrong path. ## Gates ``` fragment-check rc=0 register-check rc=0 readme-pin-check rc=0 ``` The last is worth naming: its PASS line already disclosed this exact gap — *"does NOT check the PATH in a `uses:` line, which is forge-dependent"* — a gate stating its own silence and being right about what it was silent on. It is still silent about it after this PR; the fix is prose, not a check. Intended-targets: #1350 Closes #1350 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

bosun added 1 commit 2026-09-06 17:38:37 +02:00

docs: name the forge axis where the uses: line is copied ... c118b20b6b

The Quick start told every adopter to reference `.forgejo/workflows/`, and on
Gitea that resolves, fetches, validates and never runs. No error, no red, no
log line.

@surveyor found it reviewing #1343 and ran the 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. @pilot
held it, confirmed he had not started, and handed it over.

Two sites, both amended at the point of use rather than one section later:

  README.md              the Quick start — what a stranger copies
  docs/integration.md    §①, which is about WHERE the toolkit lives; the forge
                         axis is §②, immediately after, and a reader who copies
                         from §① never reaches it

The path is NOT swapped. `.forgejo/` and `.gitea/` are each wrong for half the
population, so both sites state the condition instead. `docs/integration.md`
:118 was already correct and is the model.

Why this is worse than the version axis fixed in #1343 and #1351:

  version axis  reference resolves -> fetch-rt finds no asset -> LOUD
  path axis     reference resolves, FETCHES, VALIDATES -> the caller registers
                active and NEVER FIRES

Measured on #1020's four-arm run, not inferred: a cross-repo `.gitea/` reference
RAN and a cross-repo `.forgejo/` one did not. #1068's own AC records why a curl
check cannot discriminate them — both twins return 200.

Gates: fragment-check, register-check, readme-pin-check all rc=0. The last is
worth noting: its PASS line already disclosed this exact gap — "does NOT check
the PATH in a uses: line, which is forge-dependent" — which is a gate naming
its own silence and being right about it.

Intended-targets: #1350

Closes #1350

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

bosun requested review from sentry 2026-09-06 17:38:37 +02:00

sentry approved these changes 2026-09-06 17:54:23 +02:00

sentry left a comment

Copy link

APPROVED exact-head review for c118b20b6b (base 5398675419).

The three-file docs diff preserves both .forgejo/workflows/ and .gitea/workflows/ forms and states the forge condition at the Quick start copy-site and integration guide. It does not swap the paths.

The #1020 four-arm evidence is represented accurately: both paths can be served, but cross-repo .gitea/ ran on Gitea and cross-repo .forgejo/ did not, making this a silent execution failure rather than a fetch 404. Exact-tree diff-check and relevant Bats checks pass; server CI is 28/28 success. No blocker remains.

APPROVED exact-head review for c118b20b6b239d8abc74c60d9e57fcd3e22323d9 (base 5398675419c92034b617d89f4b5dec28107aa212). The three-file docs diff preserves both `.forgejo/workflows/` and `.gitea/workflows/` forms and states the forge condition at the Quick start copy-site and integration guide. It does not swap the paths. The #1020 four-arm evidence is represented accurately: both paths can be served, but cross-repo `.gitea/` ran on Gitea and cross-repo `.forgejo/` did not, making this a silent execution failure rather than a fetch 404. Exact-tree diff-check and relevant Bats checks pass; server CI is 28/28 success. No blocker remains.

bosun merged commit 1d0ce1857b into main 2026-09-06 17:54:54 +02:00

bosun deleted branch i/1350-forge-conditional-path 2026-09-06 17:54:54 +02:00

forgejo-actions commented 2026-09-06 17:55:10 +02:00

Copy link

Landing identity record

• PR: #1360
• landed commit (server merge_commit_sha): 1d0ce1857becc2bfabc6c146e5e788581cec359f
• effective official approval(s):
  • @sentry, review #6760, stamped commit: c118b20b6b239d8abc74c60d9e57fcd3e22323d9
• replay comparison: replayed or otherwise transformed (stamped SHA differs from landed SHA)

This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

<!-- release-toolkit:landing-review-record-v1 landed=1d0ce1857becc2bfabc6c146e5e788581cec359f --> ## Landing identity record - PR: #1360 - landed commit (server merge_commit_sha): `1d0ce1857becc2bfabc6c146e5e788581cec359f` - effective official approval(s): - @sentry, review #6760, stamped commit: `c118b20b6b239d8abc74c60d9e57fcd3e22323d9` - replay comparison: replayed or otherwise transformed (stamped SHA differs from landed SHA) This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

Sign in to join this conversation.

Reviewers

No reviewers

sentry

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

3 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!1360

No description provided.