ConfigKit/docs/roadmap/release-simplification.md

# 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.