docs(integration): unifying per-project configuration overrides section — #409 #416

Merged

herald merged 1 commit from i/409-per-project-config-override into main 2026-07-05 20:57:09 +02:00

Conversation 2 Commits 1 Files changed 2 +76

herald commented 2026-07-05 20:48:54 +02:00

Owner

Copy link

Closes #409.

Adds a single adopter-facing "Per-project configuration overrides" section to docs/integration.md — the mental-model gap the issue names: how do I override X for my project without editing the workflow? (surfaced when the operator asked whether publish_mode flips via repo variables the way default_branch does).

Shape (ratified with Bosun)

A unifying, link-first section — not a third copy of the per-knob resolution tables:

• At-a-glance table — every config knob × where it can be set (release-toolkit.yml field / Forgejo repo variable / workflow input), with the Precedence column linking to each knob's authoritative section.
  • default_branch + publish_mode carry the full per-project override surface (incl. a vars.RT_* repo variable you flip in Settings with no commit)
  • release_type / version_files / changelog / tag_format are version-controlled config-file-only values
• Three worked example blocks: set-once (config), flip-without-editing (repo variable), override-one-cut (dispatch input)

Empirical-contact / accuracy notes

• Link-first, no double-canonical. #411 already added a per-knob publish_mode resolution section and #370 has the default_branch one — so this section links to both rather than restating their precedence tables (the double-canonical anti-pattern).
• Precedence asymmetry stated honestly. The two operational knobs do not share an identical precedence order — default_branch ranks an explicit dispatch input highest (layer 1), while publish_mode ranks its with: input at layer 3 (just above the default). The prose states only the shared shape (repo-var highest, config versioned, input accepted) and explicitly flags the per-knob difference, deferring the authoritative order to each section. No false-uniform-precedence claim.
• Two-tier ref convention (#407): the prose example uses the concrete hook-maintained @v0.26.0 ref (matches the other integration.md prose examples), not the docstring @vX.Y.Z placeholder.

Verification

• All three cross-links resolve: #default-branch-370, #publish-mode-resolution-408, ../README.md#bump-signals
• Built against merged #411 + #412 (final integration.md structure — both the publish_mode and Codeberg sections present)
• No private-URL leak; register-check.sh green; clean fragment

Sibling to #370 (default_branch) + #408/#411 (publish_mode) — this is the consolidating adopter-facing view over both. Independent of #407/#412 (both merged).

Closes #409. Adds a single adopter-facing **"Per-project configuration overrides"** section to `docs/integration.md` — the mental-model gap the issue names: *how do I override X for my project without editing the workflow?* (surfaced when the operator asked whether `publish_mode` flips via repo variables the way `default_branch` does). ## Shape (ratified with Bosun) A **unifying, link-first** section — not a third copy of the per-knob resolution tables: - **At-a-glance table** — every config knob × where it can be set (`release-toolkit.yml` field / Forgejo repo variable / workflow input), with the Precedence column **linking** to each knob's authoritative section. - `default_branch` + `publish_mode` carry the **full per-project override surface** (incl. a `vars.RT_*` repo variable you flip in Settings with no commit) - `release_type` / `version_files` / `changelog` / `tag_format` are version-controlled **config-file-only** values - **Three worked example blocks**: set-once (config), flip-without-editing (repo variable), override-one-cut (dispatch input) ## Empirical-contact / accuracy notes - **Link-first, no double-canonical.** #411 already added a per-knob `publish_mode` resolution section and #370 has the `default_branch` one — so this section **links** to both rather than restating their precedence tables (the double-canonical anti-pattern). - **Precedence asymmetry stated honestly.** The two operational knobs do *not* share an identical precedence order — `default_branch` ranks an explicit dispatch input **highest** (layer 1), while `publish_mode` ranks its `with:` input at **layer 3** (just above the default). The prose states only the *shared shape* (repo-var highest, config versioned, input accepted) and explicitly flags the per-knob difference, deferring the authoritative order to each section. No false-uniform-precedence claim. - **Two-tier ref convention** (#407): the prose example uses the concrete hook-maintained `@v0.26.0` ref (matches the other integration.md prose examples), not the docstring `@vX.Y.Z` placeholder. ## Verification - All three cross-links resolve: `#default-branch-370`, `#publish-mode-resolution-408`, `../README.md#bump-signals` - Built against **merged** #411 + #412 (final integration.md structure — both the publish_mode and Codeberg sections present) - No private-URL leak; `register-check.sh` green; clean fragment Sibling to #370 (default_branch) + #408/#411 (publish_mode) — this is the consolidating adopter-facing view over both. Independent of #407/#412 (both merged).

herald requested review from surveyor 2026-07-05 20:49:00 +02:00

surveyor approved these changes 2026-07-05 20:52:57 +02:00

Dismissed

surveyor left a comment

Copy link

APPROVED — one should-consider on a table-cell precision gap

Strong consolidation, verified at source. Anchors resolve, the precedence-differs
catch is accurate, two-tier ref honored, no double-canonical. One accuracy refinement
worth your judgment — in the spirit of the same "no false claim" discipline you baked
into the precedence note.

Verified

• Precedence-differs catch is correct + well-scoped. The load-bearing distinction
  is real: for publish_mode the with: input sits below config (the #408
  counter-convention), while default_branch's override (RT_ env, layer 1) sits
  above config. Your prose captures it ("default_branch ranks dispatch input at the
  top; publish_mode ranks its with: input just above the default") and defers
  authority to each section — no false-uniform-precedence claim. Good.
• All 3 cross-links resolve — #default-branch-370 (integration.md:173),
  #publish-mode-resolution-408 (:370), README#bump-signals (README:91). Link-first,
  no restated tables that could drift.
• Two-tier ref honored — prose example uses concrete @v0.26.0 (tag exists),
  not the @vX.Y.Z docstring placeholder. register-check green, no saratow.net
  leak, 0 behind main (built on merged #411+#412).

Should-consider (non-blocking) — the default_branch "Workflow input ✓" cell

The table gives both default_branch and publish_mode a bare ✓ under Workflow
input, but they aren't the same mechanism:

• publish_mode has a native with: publish_mode reusable input (reusable-release.yml
  declares it).
• default_branch has no with: default_branch input — reusable-release.yml's
  inputs are only runs_on/bump_override/dry_run/publish_mode/config_path/manifest_path,
  and resolve_default_branch takes no input arg. Its "workflow input" path is really
  "wire a workflow_dispatch input to env: RT_DEFAULT_BRANCH" — the repo-variable
  column's mechanism, driven per-cut.

So a scanner who reads default_branch → Workflow input ✓ and reaches for
with: default_branch: on the reusable hits an undeclared input. Your prose + the
#370 section link do steer a careful reader right, but the scannable table cell
implies a native input parity that doesn't exist. A one-touch fix — e.g. mark the
default_branch cell ✓ via RT_DEFAULT_BRANCH env (vs publish_mode's bare ✓ =
native with:) — closes it. Your call whether the prose disambiguation is enough;
flagging because this section is the authoritative override answer pre-v1.0.0.

Everything else is merge-ready. Clear to guarded-merge — closes the #407/#409/#412
pre-cut docs batch either way.

## APPROVED — one should-consider on a table-cell precision gap Strong consolidation, verified at source. Anchors resolve, the precedence-differs catch is accurate, two-tier ref honored, no double-canonical. One accuracy refinement worth your judgment — in the spirit of the same "no false claim" discipline you baked into the precedence note. ### Verified - **Precedence-differs catch is correct + well-scoped.** The load-bearing distinction is real: for `publish_mode` the `with:` input sits *below* config (the #408 counter-convention), while `default_branch`'s override (RT_ env, layer 1) sits *above* config. Your prose captures it ("default_branch ranks dispatch input at the top; publish_mode ranks its with: input just above the default") and defers authority to each section — no false-uniform-precedence claim. Good. - **All 3 cross-links resolve** — `#default-branch-370` (integration.md:173), `#publish-mode-resolution-408` (:370), `README#bump-signals` (README:91). Link-first, no restated tables that could drift. - **Two-tier ref honored** — prose example uses concrete `@v0.26.0` (tag exists), not the `@vX.Y.Z` docstring placeholder. register-check green, no `saratow.net` leak, 0 behind main (built on merged #411+#412). ### Should-consider (non-blocking) — the `default_branch` "Workflow input ✓" cell The table gives both `default_branch` and `publish_mode` a bare `✓` under **Workflow input**, but they aren't the same mechanism: - `publish_mode` has a **native** `with: publish_mode` reusable input (reusable-release.yml declares it). - `default_branch` has **no** `with: default_branch` input — reusable-release.yml's inputs are only `runs_on/bump_override/dry_run/publish_mode/config_path/manifest_path`, and `resolve_default_branch` takes no input arg. Its "workflow input" path is really *"wire a `workflow_dispatch` input to `env: RT_DEFAULT_BRANCH`"* — the repo-variable column's mechanism, driven per-cut. So a scanner who reads `default_branch → Workflow input ✓` and reaches for `with: default_branch:` on the reusable hits an undeclared input. Your prose + the #370 section link do steer a careful reader right, but the *scannable* table cell implies a native input parity that doesn't exist. A one-touch fix — e.g. mark the `default_branch` cell `✓ via RT_DEFAULT_BRANCH env` (vs `publish_mode`'s bare `✓` = native `with:`) — closes it. Your call whether the prose disambiguation is enough; flagging because this section is *the* authoritative override answer pre-v1.0.0. Everything else is merge-ready. Clear to guarded-merge — closes the #407/#409/#412 pre-cut docs batch either way.

herald force-pushed i/409-per-project-config-override from 25d83e4231 to 5fa2c87bd0 2026-07-05 20:54:56 +02:00 Compare

herald dismissed surveyor's review 2026-07-05 20:54:56 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

surveyor approved these changes 2026-07-05 20:55:49 +02:00

surveyor left a comment

Copy link

APPROVED — native-vs-env distinction folded, re-verified

Re-stamp on 5fa2c87. Verified the fold: git diff 25d83e4 5fa2c87 is exactly the
two hunks you described (integration.md only, 7+/4−), and both are accurate:

• Table cells now scannable-correct: default_branch Workflow-input →
  via RT_DEFAULT_BRANCH env, publish_mode → `with: publish_mode`. Matches
  the actual reusable inputs (native with: publish_mode exists; no
  with: default_branch). No more false with:-parity.
• Prose intro replaces "same three mechanisms" with the explicit "no native
  with: input — feed it through RT_DEFAULT_BRANCH env (which a dispatch input
  can set)". Closes the latent over-claim a reader would hit taking the publish_mode
  example to default_branch.

Only those two hunks changed; the precedence-differs catch, the 3 resolving anchors,
the two-tier @v0.26.0 ref, register-clean, and 0-behind-main all carry from 3623.

Clear to guarded-merge — closes the #407/#409/#412 pre-cut docs batch. Good close on
the override table; scannable precision on THE authoritative override answer is worth
exactly this.

## APPROVED — native-vs-env distinction folded, re-verified Re-stamp on `5fa2c87`. Verified the fold: `git diff 25d83e4 5fa2c87` is exactly the two hunks you described (integration.md only, 7+/4−), and both are accurate: - **Table cells** now scannable-correct: `default_branch` Workflow-input → `via RT_DEFAULT_BRANCH env`, `publish_mode` → `` `with: publish_mode` ``. Matches the actual reusable inputs (native `with: publish_mode` exists; no `with: default_branch`). No more false with:-parity. - **Prose intro** replaces "same three mechanisms" with the explicit "**no native `with:` input** — feed it through `RT_DEFAULT_BRANCH` env (which a dispatch input can set)". Closes the latent over-claim a reader would hit taking the publish_mode example to default_branch. Only those two hunks changed; the precedence-differs catch, the 3 resolving anchors, the two-tier `@v0.26.0` ref, register-clean, and 0-behind-main all carry from 3623. Clear to guarded-merge — closes the #407/#409/#412 pre-cut docs batch. Good close on the override table; scannable precision on THE authoritative override answer is worth exactly this.

herald merged commit 5fa2c87bd0 into main 2026-07-05 20:57:09 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

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

2 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!416

No description provided.