# Release Policy **Base Policy Version:** 1.4 **Last Updated**: 2026-09-28 **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 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 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 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, dependency maintenance, testing, or local target-build validation. Post-publication consumer retrieval is optional, as described under Release Model. The release procedure must define the module path, authoritative remote, supported Go versions and operating-system/architecture targets, prerequisite dependency acquisition, and the exact verification commands once established. The default tests themselves remain deterministic and offline. Additional publication channels require documented deliverables and verification before use. The Go API, documented YAML/resolution semantics, and structured diagnostic contracts all participate in compatibility review. A signature-preserving change can still break consumers. Human diagnostic wording is stable only where a contract expressly promises it. Minimum Go version and platform support changes also require an explicit compatibility assessment. ### Platform support Linux is the release-validated platform. macOS has best-effort support: keeping it working remains desirable, but neither native macOS validation nor Darwin cross-builds are release gates. Missing macOS evidence or a macOS-specific failure does not by itself block a release. Voluntary checks and fixes are welcome; there is no guarantee that each release has been validated on macOS. The [release procedure](../release.md#release-identity-and-support) owns target architectures and required Linux checks. This support change applies to upcoming releases; historical release notes and their validation records remain unchanged. The v0.3.0 release note must explain the change in Compatibility, with version selection following this policy's existing compatibility rules. ## Release Model 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. 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. 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. 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. ## Versioning And Compatibility Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with no leading zeroes. Each version must be unused locally and in every configured remote or publication channel before publication begins. Unless an adopted policy explicitly supports and defines prereleases, prerelease versions are not permitted. For releases at or after `v1.0.0`: - a major release may make intentional incompatible changes; - a minor release may add backward-compatible behavior; and - a patch release may make backward-compatible fixes. Before `v1.0.0`, a minor release may change a documented public, operational, configuration, data, integration, or compatibility contract when the release note explains the impact and required consumer action. A patch release must not intentionally break those contracts within its minor line. A repository with additional compatibility promises must define them in its adopted policy or canonical contract documentation. A release note may explain a compatibility change, but it must not redefine the current compatibility contract. ## Release Documentation Every release made under this policy must include `docs/releases/.md` in the tagged source tree. The filename must use the complete version tag, and the document must begin with a title containing the product name and that exact version. Every new release note must contain these sections: ```markdown # vMAJOR.MINOR.PATCH This release ... ## Summary ## Compatibility ## Upgrade ## Changes ``` Use an explicit statement such as "No action required" when a section has no substantive content. Release notes are immutable historical summaries. They should link to current canonical documentation for exact behavior. Every affected canonical document must be updated in the same candidate; a release note must not substitute for current documentation or defer required documentation changes. Each new release note must end with the release navigation defined by the [OSS policy](oss.md#discoverability). Preserve those links on a hosted download page if one is used. The release procedure owns URL construction and channel treatment. This is ordinary preparation, not a new network check or approval gate; historical release notes are unchanged. ## Candidate Preparation And Validation 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 runs one full offline race suite, one full vet pass, and CGO-disabled Linux amd64/arm64 builds. The race suite protects library behavior, ownership, and concurrent use; it includes examples, documentation links, consumer fixtures, and package boundaries without separate runs. Full vet checks more than the subset normally run by tests, so test-time vet is disabled. The two cross-builds cover supported configurations that native race compilation does not. A second toolchain is optional and non-gating. All Go checks use readonly module mode and an offline dependency cache. Formatting and whitespace remain ordinary development checks. Review module tidiness when dependencies change, rather than auditing it on every release. 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. 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 Immediately before publication, the maintainer or release automation must fetch the current primary branch and tags from the authoritative remote and verify all of the following: - the version has the required format and is not already published; - the current branch is the primary release branch; - the worktree and index are clean; - the current commit is the recorded, validated candidate; - the authoritative remote branch points to that same commit; - the matching release note exists in that commit and has the required title and sections; - 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 publishing it. Publish only the exact intended ref and deliverables. Broad operations such as `git push --tags` are discouraged because they can publish unreviewed refs unrelated to the release. The repository-specific procedure must make these guards executable or give copyable commands for performing them. ## Immutability And Correction 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 may be removed after confirming that it was never published or used by a release channel. If publication or post-publication verification reveals a defect, leave the published release intact. Correct the defect on the primary branch, choose a new patch version or other semantically appropriate new version, write a new matching release note, and perform the complete release procedure again. A distribution channel's supported yank, deprecation, or advisory mechanism may warn consumers away from a defective release, but it must not replace that release's contents or reuse its version. ## Repository Release Procedure Every adopting repository must maintain `docs/release.md` as the canonical maintainer runbook for implementing this policy. It must define, in execution order: 1. maintainer prerequisites and required access; 2. version selection and compatibility review; 3. release-note creation; 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. 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 optional consumer verification path. It must link to this policy instead of restating or redefining its requirements. ## Policy Exceptions Any exception to this policy must be explicitly documented in this section, including the repository constraint requiring it, its rationale, scope, and compensating controls. Customizing release mechanics must not silently weaken the policy's integrity, validation, documentation, verification, or immutability requirements. 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 minor-version increment. The release note must explain the renamed directive, the lack of a legacy alias, and the newly reserved application key. This exception does not apply to subsequent releases or waive any validation or publication gate. For v0.2.0 only, the maintainer accepted the successful native macOS check at `244104f` for the final candidate, provided subsequent changes are documentation 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.