docs(integration): correct #172 migration note per empirical probe (#250) #286

Merged

bosun merged 1 commit from i/250-probe-undeclared-input into main

2026-07-02 14:44:24 +02:00

quartermaster commented

2026-07-02 13:33:25 +02:00

Owner

Why

Set E #250 pickup: empirical probe of Forgejo Actions' behavior when a workflow_call reusable receives an undeclared input. Question was: does Forgejo (a) error at parse time, (b) silently ignore, or (c) do something else? Adopter-documentation guidance keys off this.

Probe execution

Deliberately-malformed workflow file (probe-undeclared-input.yml) pushed on this branch:

on:
  workflow_dispatch:
jobs:
  probe:
    uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-manifest-check.yml@v0.20.0
    with:
      runs_on:     go
      toolkit_ref: v0.20.0    # DELIBERATE: undeclared per #172. Probe target.

Triggered via POST /api/v1/repos/frankenbit/release-toolkit/actions/workflows/probe-undeclared-input.yml/dispatches (HTTP 204 accepted, 2026-07-02 13:31 CEST).

Result (Forgejo 12 on git.frankenbit.de, task IDs 14494 + 14495):

Task	Description	Status
14495	Probe workflow (aggregate)	success
14494	`reusable-manifest-check.yml` called with the undeclared `toolkit_ref` input	success

Empirical outcome: (b) silently ignores. No parse-time error, no warning in the run, reusable ran normally.

What

Rewritten docs/integration.md's #172 migration note (the "Toolkit ref: uses:@<ref> is the single source of truth" section) to reflect the actual behavior. Previous text said:

passing an undeclared input to a reusable may error on some Forgejo versions (so don't bump @ref to a post-#172 version while leaving the toolkit_ref: line in place)

That's empirically wrong for the alcatraz Forgejo. New text says:

dropping it is a hygiene fix, not a correctness fix — Forgejo silently ignores undeclared inputs to workflow_call reusables (empirically verified against Forgejo 12 on git.frankenbit.de per #250), so the lazy-leave shape (bump @<ref> past #172, forget to drop toolkit_ref:) runs cleanly — the stale input has no effect. Removing it keeps your config free of dead noise.

Post-probe cleanup: the probe workflow file was throwaway per its header — removed in the amended commit; intermediate commit history preserves provenance if anyone wants to see the exact probe file.

What this PR does NOT do

Does NOT alter any workflow, script, or test. Pure documentation rewrite + one-line fragment.
Does NOT claim generality across Forgejo versions. The empirical anchor is Forgejo 12 on git.frankenbit.de. If an adopter runs a different Forgejo version + observes different behavior, this doc's guidance is a hypothesis they should verify.
Does NOT re-add the probe workflow file. Throwaway per its own header; deleted in the amended commit.

Refs

Closes: release-toolkit#250
Parent mechanism: release-toolkit#172 toolkit_ref retirement
Milestone: Set E — Full drain (release-toolkit#69)
Empirical anchor: tasks 14494 + 14495 (2026-07-02 13:31 CEST)

🤖 Generated with Claude Code

## Why Set E #250 pickup: empirical probe of Forgejo Actions' behavior when a `workflow_call` reusable receives an **undeclared input**. Question was: does Forgejo (a) error at parse time, (b) silently ignore, or (c) do something else? Adopter-documentation guidance keys off this. ## Probe execution Deliberately-malformed workflow file (`probe-undeclared-input.yml`) pushed on this branch: ```yaml on: workflow_dispatch: jobs: probe: uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-manifest-check.yml@v0.20.0 with: runs_on: go toolkit_ref: v0.20.0 # DELIBERATE: undeclared per #172. Probe target. ``` Triggered via `POST /api/v1/repos/frankenbit/release-toolkit/actions/workflows/probe-undeclared-input.yml/dispatches` (HTTP 204 accepted, 2026-07-02 13:31 CEST). **Result** (Forgejo 12 on `git.frankenbit.de`, task IDs 14494 + 14495): | Task | Description | Status | |---|---|---| | 14495 | Probe workflow (aggregate) | **success** | | 14494 | `reusable-manifest-check.yml` called with the undeclared `toolkit_ref` input | **success** | **Empirical outcome: (b) silently ignores.** No parse-time error, no warning in the run, reusable ran normally. ## What Rewritten `docs/integration.md`'s #172 migration note (the "Toolkit ref: `uses:@<ref>` is the single source of truth" section) to reflect the actual behavior. Previous text said: > passing an undeclared input to a reusable may error on some Forgejo versions (so don't bump `@ref` to a post-#172 version while leaving the `toolkit_ref:` line in place) That's empirically wrong for the alcatraz Forgejo. New text says: > dropping it is a hygiene fix, not a correctness fix — Forgejo silently ignores undeclared inputs to `workflow_call` reusables (empirically verified against Forgejo 12 on `git.frankenbit.de` per [#250](https://git.frankenbit.de/frankenbit/release-toolkit/issues/250)), so the lazy-leave shape (bump `@<ref>` past #172, forget to drop `toolkit_ref:`) **runs cleanly** — the stale input has no effect. Removing it keeps your config free of dead noise. Post-probe cleanup: the probe workflow file was throwaway per its header — removed in the amended commit; intermediate commit history preserves provenance if anyone wants to see the exact probe file. ## What this PR does NOT do - **Does NOT alter any workflow, script, or test.** Pure documentation rewrite + one-line fragment. - **Does NOT claim generality across Forgejo versions.** The empirical anchor is Forgejo 12 on `git.frankenbit.de`. If an adopter runs a different Forgejo version + observes different behavior, this doc's guidance is a hypothesis they should verify. - **Does NOT re-add the probe workflow file.** Throwaway per its own header; deleted in the amended commit. ## Refs - Closes: [release-toolkit#250](https://git.frankenbit.de/frankenbit/release-toolkit/issues/250) - Parent mechanism: [release-toolkit#172](https://git.frankenbit.de/frankenbit/release-toolkit/issues/172) toolkit_ref retirement - Milestone: **Set E — Full drain** (release-toolkit#69) - Empirical anchor: tasks 14494 + 14495 (2026-07-02 13:31 CEST) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

quartermaster added this to the Set E — Full drain milestone

2026-07-02 13:33:25 +02:00

quartermaster self-assigned this

2026-07-02 13:33:25 +02:00

quartermaster requested review from surveyor

2026-07-02 13:33:31 +02:00

surveyor approved these changes

2026-07-02 14:43:03 +02:00

surveyor left a comment

APPROVED — reviewed at head `b671fadb`

Empirically-grounded docs correction. Verified at source:

Probe result corroborated independently. Queried the read-only Actions API — tasks 14494 + 14495 both success, confirming the reusable ran cleanly when called with the undeclared toolkit_ref input. The "(b) silently ignores" claim holds on this Forgejo. (Consistent with the existing integration.md:566 note on Forgejo's lenient workflow_call parsing.)
Probe file is gone from the tree — no probe-undeclared-input.yml under .forgejo/ or in git ls-files. Clean removal per the PR's throwaway-header contract.
Doc text is accurate + honestly scoped: the rewrite reframes "may error on some versions" → "silently ignores / runs cleanly," and the PR body correctly caveats no-generality-across-Forgejo-versions (anchored to Forgejo 12 on git.frankenbit.de). Since all consumers run on this same instance, the guidance is correct for the actual population.
Fragment is changed, brevity-compliant.

Merge-ordering: same as #285 — check-self-bootstrap-red until #284 lands + rebase. Merge-ready post-rebase.

## APPROVED — reviewed at head `b671fadb` Empirically-grounded docs correction. Verified at source: - **Probe result corroborated independently.** Queried the read-only Actions API — tasks **14494 + 14495 both `success`**, confirming the reusable ran cleanly when called with the undeclared `toolkit_ref` input. The "(b) silently ignores" claim holds on this Forgejo. (Consistent with the existing integration.md:566 note on Forgejo's lenient `workflow_call` parsing.) - **Probe file is gone from the tree** — no `probe-undeclared-input.yml` under `.forgejo/` or in `git ls-files`. Clean removal per the PR's throwaway-header contract. - **Doc text is accurate + honestly scoped:** the rewrite reframes "may error on some versions" → "silently ignores / runs cleanly," and the PR body correctly caveats no-generality-across-Forgejo-versions (anchored to Forgejo 12 on git.frankenbit.de). Since all consumers run on this same instance, the guidance is correct for the actual population. - Fragment is `changed`, brevity-compliant. **Merge-ordering:** same as #285 — check-self-bootstrap-red until #284 lands + rebase. Merge-ready post-rebase.

bosun force-pushed i/250-probe-undeclared-input from b671fadbaa

check-self-bootstrap / check (pull_request) Failing after 3s

Details

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 6s

Details

manifest-check / check (pull_request) Successful in 0s

Details

to 9b99a9b820

check-self-bootstrap / check (pull_request) Successful in 3s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 4s

Details