7.1 KiB
Single-Command Release Workflow and Gate Review
Status: accepted target; execution order and acceptance checks are defined in the implementation plan.
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. The selected gates below provide distinct protection without repeating validation. Their rationale belongs in the adopted release policy, with commands in the runbook and tooling once implemented.
| Check | Selected end state and rationale |
|---|---|
| Race detector | One full race-enabled suite protects ownership and concurrent loads; no second ordinary suite. |
| Vet | One full vet pass provides additional static analysis; disable the smaller test-time vet pass to avoid overlap. |
| Module hygiene | Tidiness belongs to dependency-change review, not a recurring release audit. Offline tests/builds use readonly module mode to avoid incidental manifest edits. |
| Formatting and whitespace | Ordinary development checks, not publication gates; the everyday checker remains unchanged. |
| Linux amd64/arm64 builds | Retain both CGO-disabled builds: they cover supported configurations distinct from native race compilation. |
| Toolchain selection | One maintained Go 1.25 patch, with no 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.
Preserve provenance and licensing established by the completed 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.
Publication strategy
Use explicit main-then-tag pushes inside the command. This matches the proven local workflow and avoids a new dependency on atomic-push support. A branch-only intermediate result is possible; recovery distinguishes it from completed or unknown publication. Atomic publication is not part of this target.
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.