feat(config): layered resolution for publish_mode matching default_branch pattern (v1.0.0 must-fix) #408

New issue

Closed

opened 2026-07-05 20:12:47 +02:00 by bosun · 0 comments

bosun commented

2026-07-05 20:12:47 +02:00

Owner

Empirical finding

release-toolkit v0.26.0 has a design-consistency gap between two similarly-shaped config knobs:

default_branch (per #370): full 6-layer resolution — RT_DEFAULT_BRANCH env var → config field → workflow-context → Forgejo API → git-ref → fail-loud. Documented at docs/integration.md line 132: 'Or as a Forgejo repo variable (Settings → Actions → Variables → RT_DEFAULT_BRANCH) that the reusable picks up via vars.RT_DEFAULT_BRANCH automatically.'
publish_mode: workflow_call input only. No env var, no config field, no repo variable, no fallback. Adopter must edit the consumer workflow to override the default per-project.

Adopter journey exposing the gap: operator sets up demo repo (#382) with default_branch: master via config, works cleanly per #370's layering. Operator asks whether publish_mode can be flipped per-project via repo variables (same pattern) — no. Design-consistency violation forces workflow edit + PR round for a per-project preference that should be one variable set.

Blocking rationale

Operator directive 2026-07-05: land pre-v1.0.0 cut per SemVer stability contract (#338). Config interface should be clean + stable AT the major cut. Adding layered resolution post-v1.0.0 is not breaking (adds fallbacks, doesn't remove existing paths) but the semantic surface should be complete at v1.0.0 — adopters pinning @v1.0.0 get the full config vocabulary.

Fix path

Extend publish_mode to match default_branch's layered resolution:

Layer 1 (highest): RT_PUBLISH_MODE env var / vars.RT_PUBLISH_MODE repo variable / workflow_dispatch input
Layer 2: publish_mode: field in release-toolkit.yml config
Layer 3: workflow_call with: publish_mode: (already exists)
Layer 4 (default): 'draft' per #332

Precedence order: adopter explicit override (layer 1) → version-controlled config (layer 2) → workflow-call-input (layer 3) → default (layer 4).

Verification AC

vars.RT_PUBLISH_MODE set to 'immediate' in a consumer repo flips the default without editing the workflow
RT_PUBLISH_MODE=immediate env var in a consumer workflow flips the default
publish_mode: immediate in release-toolkit.yml flips the default
All three overrides tested via bats
docs/integration.md documents the resolution chain (parallel to default_branch's table)
No regression: existing consumers pinning @v0.26.0 semantics via workflow input keep working

Sibling of #370 (default_branch layered resolution) — this closes the design-consistency gap
Sibling of docs tracker filed alongside (adopter-facing per-project configuration override section)
Depends-on: #338 (SemVer stability contract) — v1.0.0 semantic-surface completion
Historical: #332 (draft-default flip) is the layer-4 default this extends

Anchor

Operator ratified 2026-07-05 as v1.0.0 must-fix per SemVer stability contract (#338): config interface should be clean + stable AT the major cut, not iteratively adjusted post-v1.0.0. Surfaced during demo repo (#382) empirical adoption: operator asked whether publish_mode could be flipped per-project via repo variables (as default_branch can, per #370), found no such mechanism exists, exposing a design-consistency gap between the two similarly-shaped config knobs.

BLOCKING v1.0.0.

## Empirical finding release-toolkit v0.26.0 has a design-consistency gap between two similarly-shaped config knobs: - **default_branch** (per #370): full 6-layer resolution — RT_DEFAULT_BRANCH env var → config field → workflow-context → Forgejo API → git-ref → fail-loud. Documented at docs/integration.md line 132: 'Or as a Forgejo repo variable (Settings → Actions → Variables → RT_DEFAULT_BRANCH) that the reusable picks up via vars.RT_DEFAULT_BRANCH automatically.' - **publish_mode**: workflow_call input only. No env var, no config field, no repo variable, no fallback. Adopter must edit the consumer workflow to override the default per-project. Adopter journey exposing the gap: operator sets up demo repo (#382) with default_branch: master via config, works cleanly per #370's layering. Operator asks whether publish_mode can be flipped per-project via repo variables (same pattern) — no. Design-consistency violation forces workflow edit + PR round for a per-project preference that should be one variable set. ## Blocking rationale **Operator directive 2026-07-05**: land pre-v1.0.0 cut per SemVer stability contract (#338). Config interface should be clean + stable AT the major cut. Adding layered resolution post-v1.0.0 is not breaking (adds fallbacks, doesn't remove existing paths) but the semantic surface should be complete at v1.0.0 — adopters pinning @v1.0.0 get the full config vocabulary. ## Fix path Extend publish_mode to match default_branch's layered resolution: Layer 1 (highest): `RT_PUBLISH_MODE` env var / `vars.RT_PUBLISH_MODE` repo variable / workflow_dispatch input Layer 2: `publish_mode:` field in release-toolkit.yml config Layer 3: workflow_call `with: publish_mode:` (already exists) Layer 4 (default): 'draft' per #332 Precedence order: adopter explicit override (layer 1) → version-controlled config (layer 2) → workflow-call-input (layer 3) → default (layer 4). ## Verification AC - `vars.RT_PUBLISH_MODE` set to 'immediate' in a consumer repo flips the default without editing the workflow - `RT_PUBLISH_MODE=immediate` env var in a consumer workflow flips the default - `publish_mode: immediate` in release-toolkit.yml flips the default - All three overrides tested via bats - docs/integration.md documents the resolution chain (parallel to default_branch's table) - No regression: existing consumers pinning @v0.26.0 semantics via workflow input keep working ## Related - Sibling of #370 (default_branch layered resolution) — this closes the design-consistency gap - Sibling of docs tracker filed alongside (adopter-facing per-project configuration override section) - Depends-on: #338 (SemVer stability contract) — v1.0.0 semantic-surface completion - Historical: #332 (draft-default flip) is the layer-4 default this extends ## Anchor Operator ratified 2026-07-05 as v1.0.0 must-fix per SemVer stability contract (#338): config interface should be clean + stable AT the major cut, not iteratively adjusted post-v1.0.0. Surfaced during demo repo (#382) empirical adoption: operator asked whether publish_mode could be flipped per-project via repo variables (as default_branch can, per #370), found no such mechanism exists, exposing a design-consistency gap between the two similarly-shaped config knobs. BLOCKING v1.0.0.

bosun added the

priority/critical

size/L

kind/feature

labels

2026-07-05 20:12:47 +02:00