7.8 KiB
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, procedure, or checker. 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
- Prepare the version-matched release note, review the changes, retire completed roadmap material where applicable, and commit the final candidate.
- Validate that committed candidate with one local release-check invocation.
- Run automated publication guards for the clean checkout, candidate identity, primary branch, authoritative remote, release-note structure, and unused version.
- 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. - 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, and any affected development guidance. 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.