eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align release policy and complete policy adoption

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 00:32:01 +00:00
parent b5a919b8c5
commit 897203dd8f
6 changed files with 66 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/policy/release.md
View File

@@ -1,22 +1,25 @@
# Release Policy
**Base Policy Version:** 1.0
**Base Policy Version:** 1.4
**Last Updated:** 2026-09-26
**Last Updated**: 2026-09-28
The licensing-footer requirement incorporates upstream release policy v1.2;
other release-workflow changes from that version are not adopted here.
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
ConfigKit retains its separately invoked checker and guarded
[release procedure](../release.md). A single publication command and review of
the current gates are future work under the
[release-workflow roadmap](../roadmap/release.md).
## Purpose
This policy defines the minimum requirements for selecting, validating,
publishing, verifying, and correcting releases. Its goal is to make every
release intentional, reproducible from an exact source revision, documented
for consumers, and safe from retrospective replacement.
This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents.
The repository-specific commands that implement these requirements belong in
`docs/release.md`. Historical release summaries belong in `docs/releases/`.
Neither document may weaken this policy.
The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements.
## ConfigKit applicability
@@ -25,7 +28,7 @@ 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
local target-build validation. Post-publication consumer retrieval is optional,
as documented under Policy Exceptions.
as described under Release Model.
The release procedure must define the module path, authoritative remote,
supported Go versions and operating-system/architecture targets, prerequisite
@@ -55,33 +58,30 @@ selection following this policy's existing compatibility rules.
## Release Model
A release consists of:
A source release identifies one exact committed source revision through an
immutable version tag and a version-matched, checked-in release note. ConfigKit's
primary release branch is `main`; its tags are annotated. The
[release procedure](../release.md) names the authoritative publication remote.
- one exact source commit reachable from the repository's primary branch;
- one immutable version tag identifying that commit;
- one version-matched, checked-in release note; and
- every artifact, image, package, registry entry, or other deliverable the
repository declares for that release.
A successful push of the intended tag, with its source commit available on the
authoritative primary branch, completes the release. ConfigKit publishes the
committed candidate to `main` before pushing only the intended tag.
The repository's primary branch is `main` unless an adopted policy documents
an exception. A release candidate must be committed and pushed to that branch
before its release tag is published.
Release commands must finish at successful publication. They must not wait for
or poll CI, require successful CI status, inspect downloadable artifacts, or
check consumer installation or Go module availability as completion gates.
Optional remote tag read-back and fresh consumer retrieval do not delay release
completion.
The source tag is the authoritative release identity. Published deliverables
must be traceable to the tagged source and must agree with its version. A
repository may publish source only. When it publishes additional deliverables,
its release procedure must enumerate them and define how each is built,
identified, published, and verified.
ConfigKit publishes source only. If additional deliverables are deliberately
adopted, they must be traceable to the tagged source, identify the same version,
and have documented publication responsibilities and verification.
Release automation may validate or publish a release only when its exact
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
@@ -196,10 +196,10 @@ copyable commands for performing them.
## Immutability And Correction
Published version tags and published deliverables are immutable. Do not move,
overwrite, recreate, or delete a published tag. Do not replace an artifact,
image, package, checksum, signature, provenance statement, or release note
under an already published version.
Published version tags and published contents are immutable. Do not move,
overwrite, recreate, or delete a published tag, or replace a published artifact,
checksum, signature, provenance statement, or release note under that version.
The checked-in note at the immutable tag is that release's historical record.
If validation fails before publication, correct the candidate, rerun the
complete gates, and repeat the publication guards. An unpublished local tag
@@ -245,15 +245,6 @@ 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
@@ -266,6 +257,3 @@ For v0.2.0 only, the maintainer accepted the successful native macOS check at
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 and guarded publication remain mandatory; post-publication
verification is optional in the [release procedure](../release.md).