docs(integration): adopter-facing per-project configuration override section (v1.0.0 must-fix) #409

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 docs describe individual config knobs (default_branch, publish_mode, version_files, changelog, tag_format) but lack a single adopter-facing section answering: 'how do I override X for my specific project without editing the workflow?'

Adopter journey exposing the gap: operator asks whether publish_mode can be flipped via Codeberg's Project Variables (parallel to default_branch's vars.RT_DEFAULT_BRANCH mechanism which they know from #370). Answer requires reading:

reusable-release.yml description: string (workflow input only)
integration.md's default_branch table (repo variable IS supported)
inferring by absence that publish_mode is NOT similar

Should be one clear section: 'Per-project configuration overrides — this is how you set each knob without touching your workflow.'

Blocking rationale

Operator directive 2026-07-05: land pre-v1.0.0 cut per SemVer stability contract (#338). Adopter mental model of the config surface should be complete + coherent AT the major cut. Documentation gaps at v1.0.0 tell adopters 'this is unfinished'; a v1.1.0 doc addition tells them 'we didn't think about your journey.'

Fix path

Add docs/integration.md section 'Per-project configuration overrides' or similar. Table shape:

Knob	workflow input (dispatch)	workflow_call `with:`	Repo variable	Env var	config file	Precedence
default_branch	yes	yes	vars.RT_DEFAULT_BRANCH	RT_DEFAULT_BRANCH	`default_branch:`	env > config > vars > input
publish_mode	yes	yes	vars.RT_PUBLISH_MODE	RT_PUBLISH_MODE	`publish_mode:`	env > config > vars > input
...	...	...	...	...	...	...

Plus example blocks: 'set once for this repo' + 'override for one cut only' + 'set via CLI dispatch' — three common adopter workflows.

Verification AC

Adopter reading the section can answer 'how do I flip publish_mode for my repo' without cross-referencing multiple sources
Table covers all configurable knobs (default_branch, publish_mode, plus any others)
Round-5 external cold-read finds no per-project-config confusion

Depends-on: sibling design tracker (publish_mode layered resolution) — this docs the implementation
Related to #370 (default_branch resolution)
Related to #407 (adopter-copy-paste wiring docstring drift) — same adopter-journey-doc-gap parent class

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. Herald docs territory. Land AFTER design tracker merges so both knobs (default_branch + publish_mode) document under the same shape.

## Empirical finding release-toolkit v0.26.0 docs describe individual config knobs (default_branch, publish_mode, version_files, changelog, tag_format) but lack a **single adopter-facing section** answering: 'how do I override X for my specific project without editing the workflow?' Adopter journey exposing the gap: operator asks whether publish_mode can be flipped via Codeberg's Project Variables (parallel to default_branch's `vars.RT_DEFAULT_BRANCH` mechanism which they know from #370). Answer requires reading: - reusable-release.yml `description:` string (workflow input only) - integration.md's default_branch table (repo variable IS supported) - inferring by absence that publish_mode is NOT similar Should be one clear section: 'Per-project configuration overrides — this is how you set each knob without touching your workflow.' ## Blocking rationale Operator directive 2026-07-05: land pre-v1.0.0 cut per SemVer stability contract (#338). Adopter mental model of the config surface should be complete + coherent AT the major cut. Documentation gaps at v1.0.0 tell adopters 'this is unfinished'; a v1.1.0 doc addition tells them 'we didn't think about your journey.' ## Fix path Add `docs/integration.md` section 'Per-project configuration overrides' or similar. Table shape: | Knob | workflow input (dispatch) | workflow_call `with:` | Repo variable | Env var | config file | Precedence | |---|---|---|---|---|---|---| | default_branch | yes | yes | vars.RT_DEFAULT_BRANCH | RT_DEFAULT_BRANCH | `default_branch:` | env > config > vars > input | | publish_mode | yes | yes | vars.RT_PUBLISH_MODE | RT_PUBLISH_MODE | `publish_mode:` | env > config > vars > input | | ... | ... | ... | ... | ... | ... | ... | Plus example blocks: 'set once for this repo' + 'override for one cut only' + 'set via CLI dispatch' — three common adopter workflows. ## Verification AC - Adopter reading the section can answer 'how do I flip publish_mode for my repo' without cross-referencing multiple sources - Table covers all configurable knobs (default_branch, publish_mode, plus any others) - Round-5 external cold-read finds no per-project-config confusion ## Related - Depends-on: sibling design tracker (publish_mode layered resolution) — this docs the implementation - Related to #370 (default_branch resolution) - Related to #407 (adopter-copy-paste wiring docstring drift) — same adopter-journey-doc-gap parent class ## 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. Herald docs territory. Land AFTER design tracker merges so both knobs (default_branch + publish_mode) document under the same shape.

bosun added the

priority/high

size/S

kind/docs

labels

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