Simplify local release validation and publication

This commit is contained in:
2026-09-23 18:10:37 +00:00
parent c5a2ddee7a
commit aead20fae4
6 changed files with 273 additions and 276 deletions

View File

@@ -21,7 +21,8 @@ ConfigKit adopts a source-only Go module release model. The source tag and
version-matched release note are the declared deliverables. Standalone binaries,
container images, and separate binary/package-registry publication are not
required. This does not waive source compilation, module hygiene, testing, or
consumer-facing module retrieval and build verification.
local target-build validation. Post-publication consumer retrieval is optional,
as documented under Policy Exceptions.
The release procedure must define the module path, authoritative remote,
supported Go versions and operating-system/architecture targets, prerequisite
@@ -74,6 +75,10 @@ responsibility is documented. Automation must not silently change the source
candidate, move a published tag, replace a published deliverable, or repair a
release in place.
A successful push of the intended annotated tag completes the source-only release.
Never wait for CI or use its status as a readiness or completion gate. Optional
post-publication checks must not delay reporting success.
## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
@@ -132,38 +137,28 @@ current documentation or defer required documentation changes.
## Candidate Preparation And Validation
Each repository must provide one documented release-check command or script
that exercises the complete set of automated source-candidate gates. The
repository-specific procedure must state all additional manual gates.
ConfigKit provides one local release checker. Run it once against the final
committed candidate using one maintained patch of the minimum supported Go line
on Linux. It checks module hygiene, formatting and whitespace, the full offline
suite with the race detector, static analysis, and CGO-disabled Linux amd64/arm64
builds. Examples, documentation links, consumer fixtures, and package boundaries
are covered by that suite, not separate repeated runs. Native package compilation
is covered by the test run. A second toolchain is optional and non-gating.
The required gates are:
Commit the release note and associated changes before release validation. Record
the exact validated commit; revalidate if the candidate changes. Do not require
both pre-commit and post-commit full checker runs for unchanged content.
Do not publish uncommitted or unvalidated content. Local check failures still
block publication. Skipped test cases are reported, not separate human sign-off
requirements.
- dependency or module hygiene appropriate to the language and ecosystem;
- the complete deterministic, offline default test suite;
- race, concurrency, or equivalent safety checks where the implementation can
be meaningfully checked for those risks;
- static analysis and linting used by the repository;
- production builds for every supported target that can be built in the
release environment;
- formatting and whitespace checks;
- validation of maintained examples, configuration, schemas, generated
sources, and documentation commands where applicable;
- review of changed local documentation links;
- removal of obsolete roadmap documents under `docs/roadmap/` that describe
completed work included in the release;
- review for unintended files, generated output, credentials, private data,
and unrelated changes; and
- any additional security, compatibility, migration, packaging, or platform
checks required by the product.
Unavailable tooling or an inapplicable check must be addressed explicitly in
the adopted policy or release procedure; it must not disappear silently from
the candidate gates.
Run the complete checker while preparing the candidate. Commit the release
note and all associated code, tests, documentation, and configuration, then
run the complete checker again against the exact commit intended for release.
Do not publish a release from uncommitted or unvalidated content.
Compatibility review, release-note accuracy, removal of completed roadmaps, and
review for unintended files, credentials, private data, and unrelated changes
are ordinary preparation. The executing agent may perform them without routine
human approval or separate manual evidence records. Ask the maintainer only for
genuine unresolved decisions or missing authority. A clean existing checkout is
sufficient; a dedicated clone is optional. Dependency and toolchain update
research belongs to maintenance or relevant changes, not every release.
## Publication Guards
@@ -178,7 +173,8 @@ verify all of the following:
- the authoritative remote branch points to that same commit;
- the matching release note exists in that commit and has the required title
and sections;
- all required approvals and automated gates succeeded for that commit; and
- release publication is authorized and the local automated gates succeeded for
that commit; and
- no local or remote tag already uses the selected version.
Create the version tag against the guarded commit and verify its target before
@@ -219,17 +215,17 @@ order:
1. maintainer prerequisites and required access;
2. version selection and compatibility review;
3. release-note creation;
4. candidate preparation and the complete validation command;
5. candidate commit, push, and exact commit recording;
4. candidate preparation and commit;
5. one local validation pass, exact candidate recording, and push;
6. publication guards;
7. exact tag and deliverable publication commands;
8. authoritative remote and consumer-facing verification; and
8. completion on successful tag push and optional post-publication checks; and
9. failure handling and correction.
The procedure should use copyable, fail-fast commands where practical. It must
name the primary branch, authoritative remote, tag form, published
deliverables, supported build targets, release automation responsibilities,
and consumer verification path. It must link to this policy instead of
and optional consumer verification path. It must link to this policy instead of
restating or redefining its requirements.
## Policy Exceptions
@@ -240,6 +236,15 @@ compensating controls. Customizing release mechanics must not silently weaken
the policy's integrity, validation, documentation, verification, or immutability
requirements.
For ConfigKit's source-only releases, the maintainer accepts successful publication
of the intended tag as sufficient completion evidence. This is an explicit
exception to the shared standard's mandatory post-publication verification:
authoritative tag read-back and fresh consumer retrieval are optional and
non-gating. CI status and downstream retrieval availability must not delay release
completion. Compensating controls are local validation of the exact candidate,
automated pre-publication guards, matching remote main, verification of the local
annotated tag target, explicit ref pushes, and immutable published versions.
For v0.1.1 only, the maintainer approved renaming the reserved `_configkit` key to
`configkit` as an error-correcting point release because there are no current
consumers. This intentionally changes the v0.1.0 configuration contract without a
@@ -253,5 +258,5 @@ only. The final candidate still requires the complete Linux release checker.
This exception waives only repeating the macOS check after those documentation
changes; it does not waive other publication or verification gates.
Candidate selection, publication, and post-publication verification remain
mandatory steps in the [release procedure](../release.md).
Candidate selection and guarded publication remain mandatory; post-publication
verification is optional in the [release procedure](../release.md).