ConfigKit/docs/roadmap/release.md

Single-Command Release Workflow and Gate Review

Status: accepted target; detailed design and implementation planning remain separate.

Intent and baseline

Make source releases simple for humans and agents: one publication command validates the final committed candidate, checks publication state, and publishes only the intended refs. Keep the minimum gates justified by ConfigKit's actual risks, with no routine human intervention or waiting for CI.

Local baseline: 0adb94f59e44827908eff401d4381a398fe17107 (v0.4.1). The upstream reference is release policy v1.4 at d84a38ebab26f048cafbe59a2246700c35d29843: standard release policy.

Today, scripts/release-check.sh performs local validation; the runbook separately records a candidate commit and executes shell blocks for guards, branch push, annotated tagging, and tag push. The checker runs module hygiene, formatting and whitespace checks, one race-enabled suite, vet, and Linux amd64/arm64 cross-builds using a maintained Go 1.25 patch. Publication completes on successful tag push.

These remain the current requirements until deliberately revised. This roadmap does not itself waive existing gates.

Target release contract

ConfigKit remains a source-only Go module hosted at its authoritative Gitea remote. Releases identify a final committed source revision on main, one fresh immutable annotated version tag, and a matching checked-in release note. No binary distribution, hosted release object, or registry publication is added.

The publication command owns validation, candidate identity, guards, and explicit ref publication. Preparation still supplies the version, committed release note, and dependencies/toolchain; the command must not silently edit or commit source, choose a version, or upgrade dependencies. Publication remains subject to user authorization, not the standing local-commit policy.

The command validates the exact candidate once. An optional validation-only mode may support diagnosis but is not a prerequisite followed by duplicate validation. Do not require both everyday and release checkers. An implementation need not introduce a persistent validation cache merely to replace today's manual record.

Mechanical guards ensure a clean worktree/index on the primary branch, an unused valid version locally and on the authoritative remote, a matching release note, and exact agreement between validated source and tagged source. Publish only intended refs without discarding remote history. Ignored local files are not release content and do not alone prevent publication.

A successful intended tag push, with the source commit available on authoritative main, completes the release. Never wait for or poll CI, module availability, consumer installation, or optional verification. Do not add a successful-push remote read-back gate. If future artifact channels are adopted, delivery status must remain separate; this task introduces none.

Gate review target

Keep the full deterministic offline suite as the core check. Evaluate every additional current gate for distinct protection, cost, and overlap; do not retain or remove it solely because it appears in a template. Record the selected rationale in the adopted release policy, with commands in the runbook and implementation.

Current check	Review question
Race detector	Does its coverage of ownership and concurrent loads justify retaining it as the single full-suite mode? Avoid a second ordinary suite.
Vet	What additional static defects does it catch beyond the test invocation, and is that protection worth a separate gate?
Module hygiene	Is reproducibility protection distinct from ordinary dependency-change review and offline tests?
Formatting and whitespace	Which checks belong in ordinary development rather than blocking publication? Avoid repeated scans without distinct value.
Linux amd64/arm64 builds	Preserve existing supported targets unless deliberately changed; remove only demonstrably redundant work, not support commitments by implication.
Toolchain selection	Preserve minimum-line validation without adding a second-toolchain gate or per-release latest-version research.

Examples, consumer fixtures, documentation links, and import/public boundary tests are already in the suite; they must not become separately repeated release checks. macOS remains best-effort. No human sign-off, new linter, hardware requirement, scanner, credentials-dependent test, or remote application probe is introduced.

Documentation and recovery

Align docs/policy/release.md with upstream shared wording, preserving explicit ConfigKit decisions and the selected gate rationale. The successful-tag-push rule is a normal supported choice under the new upstream policy, not an exception requiring newly invented compensating controls.

Make docs/release.md a short executable runbook for preparation and the single command. New notes use a proportionate summary and applicable compatibility and upgrade information rather than mandatory empty sections. Preserve the licensing footer and version-specific immutable links. Derive annotated-tag summary content from the checked-in note. Keep historical notes unchanged.

Validation or guard failure stops publication with actionable diagnostics and no force updates. A failed or ambiguous push requires resolving authoritative remote state before retrying or reporting success. A transient failure does not itself require a new version. Published tags remain immutable; removing an unpublished local tag requires confirmation it was never published. Explain partial progress such as a successful branch push followed by a failed tag push.

Changes needed and scope

The work affects docs/policy/release.md, docs/release.md, release shell tooling, release_check_test.go, and relevant contributor guidance. Reuse existing validation mechanisms where appropriate; avoid a general release framework. Tests should exercise success and meaningful failure/recovery paths in disposable local repositories, without real publication or credentials. Match coverage to the chosen push strategy and protect against unintended refs or stale candidates.

Coordinate provenance and licensing with the policy roadmap. Operational documentation changes land with the implementation they describe. No library behavior, dependency update, release tag, or push is authorized by implementing this roadmap alone.

Open Decisions

Final gate set

Recommendation: use the current single race suite and Linux support matrix as the starting point, retaining additional checks only with specific nonredundant justification. Assess the remaining checks during implementation planning before changing the binding policy. This protects selected behavior without treating the existing checker as an untouchable inventory.

Alternative: retain the entire existing checker and automate only publication. This minimizes behavioral change and is a viable initial scope, but it does not complete the requested gate review unless each retained check is justified.

Publication strategy

Recommendation: retain explicit main-then-tag pushes inside the command. This matches the proven local workflow and avoids a new dependency on atomic-push support; recovery must describe a partially published sequence.

Alternative: atomically push main and the tag after validating remote ancestry. This avoids a branch-only intermediate result but requires confirming server support and adapting failure tests. Select one strategy in the implementation plan rather than silently switching between them.

Completion criteria

One documented command publishes a prepared candidate with the reviewed minimum gate set, no duplicate suite runs, and automated exact-source safeguards. Local regression tests demonstrate successful publication and safe failure handling. The policy, runbook, and scripts agree, and successful tag publication is reported without waiting for external completion evidence. Detailed stages belong in the later implementation plan, not this target-state roadmap.