ConfigKit/docs/policy/release.md

# Release Policy

**Base Policy Version:** 1.0

**Last Updated:** 2026-09-23

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

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
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:

```markdown
# <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

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.

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 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 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 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
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 and guarded publication remain mandatory; post-publication
verification is optional in the [release procedure](../release.md).