From c5a2ddee7a01d7dcaaeea97713563a5735ba0aaf Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 23 Sep 2026 18:03:25 +0000 Subject: [PATCH] Document the simplified release workflow --- docs/roadmap/release-simplification.md | 139 +++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/roadmap/release-simplification.md diff --git a/docs/roadmap/release-simplification.md b/docs/roadmap/release-simplification.md new file mode 100644 index 0000000..0c69b0d --- /dev/null +++ b/docs/roadmap/release-simplification.md @@ -0,0 +1,139 @@ +# Release Workflow Simplification + +Status: approved target, not yet implemented. + +## Intent and scope + +ConfigKit should have the minimum release gates reasonably needed for a small +source-only Go library. Favor inexpensive local automation over repeated checks +and human intervention. A successful push of the intended release tag completes +the release; CI reliability and timing must never determine release readiness +or completion. + +This roadmap records the maintainer-approved outcome of the release-gate audit. +It does not itself update the [release policy](../policy/release.md), +[procedure](../release.md), or [checker](../../scripts/release-check.sh). +Those owners must be brought into agreement when this work is implemented. +There are no library API, configuration, or runtime behavior changes in scope. + +## Target release workflow + +1. Prepare the version-matched release note, review the changes, retire completed + roadmap material where applicable, and commit the final candidate. +2. Validate that committed candidate with one local release-check invocation. +3. Run automated publication guards for the clean checkout, candidate identity, + primary branch, authoritative remote, release-note structure, and unused version. +4. Push the candidate to `main`, verify the remote branch matches the candidate, + create the annotated tag at that exact commit, and push only that tag ref. +5. Report the release complete as soon as the intended tag push succeeds. + +The candidate must remain the exact validated commit through publication. A +changed candidate requires validation again, but there is no mandatory pair of +full runs before and after committing unchanged content. A clean existing +checkout is sufficient; a dedicated clone is optional. + +Retain immutable published tags, version selection and compatibility rules, +version-matched release notes, and explicit push targets. Do not add a separate +Gitea release object, binary upload, or other deliverable to this source-only model. + +## Local automated gates + +Use one maintained patch of the minimum supported Go toolchain line (currently +Go 1.25) in a local Linux environment. Toolchains and dependencies are acquired +explicitly; the checker remains offline. Toolchain maintenance is not a mandatory +latest-version lookup on every release. + +| Check | Target treatment and reason | +| --- | --- | +| Full default test suite | Run once with `go test -race ./...`; preserve race coverage for shared-state isolation without a separate ordinary full-suite run. | +| Static analysis | Run `go vet ./...` once; it covers more than the default vet subset run by `go test`. | +| Module hygiene | Retain the disposable-copy tidy comparison without changing candidate manifests. | +| Formatting and whitespace | Retain inexpensive local checks. | +| Linux amd64/arm64 builds | Retain CGO-disabled cross-builds; these cover advertised targets and configurations distinct from the native race-test build. | +| Examples, consumer fixtures, documentation links, and package boundaries | Keep their tests in the full suite; remove separate release-time reruns already covered by that suite. | +| Separate native production builds | Remove the extra native `go build` gates; this library's packages are compiled by the test run. | +| Second Go toolchain | Make testing on a newer toolchain optional and non-gating. | +| Native filesystem evidence | Use the local suite results rather than separate manual certification. Report skipped cases without automatically requiring human approval. | + +The local release suite must still pass. Removing redundant gates does not mean +ignoring actual local test failures. macOS remains best-effort, with no required +native validation or Darwin cross-builds. + +Avoid requiring the everyday checker in addition to the release checker when it +would merely repeat the same checks. Do not introduce an approval service, +attestation framework, or new release dependency to implement this simplification. + +## Preparation without human sign-off gates + +Compatibility and version selection, release-note accuracy, reviewing the diff +for credentials or unintended content, and retiring completed roadmaps remain +normal release preparation. The executing agent may perform these tasks without +seeking routine maintainer approval or producing separate manual evidence records. + +Only genuine unresolved product decisions or missing authority require a question +to the maintainer. Preserve authorization boundaries for pushing and releasing; +the standing local-commit policy alone is not publication authorization. + +Move toolchain update research and reassessment of available YAML dependency +versions to periodic maintenance or relevant dependency changes. Do not require +external version research or renewed approval of an unchanged dependency pin for +every patch release. Dependency changes remain reviewed changes with applicable +validation and compatibility documentation. + +## Publication is the completion condition + +Never wait for CI, poll CI until it finishes, require green CI status, or treat a +missing, slow, unreliable, or failed CI run as a release blocker. This applies +both before publication and after a successful tag push. Optional CI may provide +maintenance feedback independently; it must not be a hidden release gate. + +Fresh consumer-module retrieval, remote tag read-back after a successful push, +and other post-publication smoke checks are optional and non-gating. Do not wait +for module proxy propagation or credential-dependent consumer downloads before +reporting success. Publication push failures still mean publication has not been +confirmed; the completion rule requires a successful push of the intended tag. + +An optional later check finding a defect does not authorize replacing the tag. +Use the existing immutable-release correction rules and an appropriate new +version for any correction. + +## Explicit policy exception + +The adopted release policy must record the deliberate exception to the shared +standard's mandatory post-publication verification requirement: + +- Scope: ConfigKit's source-only tag publication; subsequent authoritative + read-back and fresh consumer retrieval are optional, not completion gates. +- Rationale: the maintainer accepts a successful intended tag push as sufficient + publication evidence and rejects dependence on CI or downstream retrieval + availability for release completion. +- Compensating controls: local validation of the exact candidate, automated + pre-publication guards, matching remote `main`, an annotated tag with verified + local target, explicit ref pushes, and immutable published versions. + +Record this exception openly rather than retaining contradictory mandatory +verification wording elsewhere. Preserve historical release notes and scoped +historical exceptions unchanged. + +## Affected owners and completion criteria + +Implementation must reconcile the release policy, release procedure, checker, +relevant [check-script tests](../../release_check_test.go), and any affected +[development guidance](../development.md). Current documentation must describe +only the implemented workflow once the change lands. + +Completion requires: + +- One local validation pass for the final candidate, with the retained checks + and no duplicate full-suite or focused subset runs. +- No required human sign-off, dedicated clone, second toolchain, latest-version + research, CI waiting, or post-publication consumer verification. +- Automated safeguards still prevent publishing an unvalidated or unintended + candidate or reusing an existing version. +- Tests and documentation agree on the reduced workflow, including failure + handling and completion immediately after successful tag publication. +- Validation of the changes uses local tests and disposable fixtures; implementing + this roadmap does not itself authorize a real release or remote publication. + +There are no outstanding product decisions for this target. A later implementation +plan may sequence the work without expanding these gates or guarantees.