ConfigKit/docs/policy/release.md

Release Policy

Base Policy Version: 0.1.0

Last Updated: 2026-09-12

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.

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.

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, module hygiene, testing, or consumer-facing module retrieval and build verification.

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 owns target architectures and required Linux checks. This support change applies to upcoming releases; historical release notes and their validation records remain unchanged. The next release note must explain the change in Compatibility, with version selection following this policy's existing compatibility rules.

Release Model

A release consists of:

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

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.

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.

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/<version>.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:

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

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.

The required gates are:

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

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;
• all required approvals and 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 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.

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 the complete validation command;
5. candidate commit, push, and exact commit recording;
6. publication guards;
7. exact tag and deliverable publication commands;
8. authoritative remote and consumer-facing verification; 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 restating or redefining its requirements.

Policy Exceptions

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.

Candidate selection, publication, and post-publication verification remain mandatory steps in the release procedure.