# 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's [release procedure](../release.md) uses one publication command
with the selected local checker and explicit main-then-tag pushes.

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

A failed or ambiguous push requires resolving the authoritative remote state
before declaring success or retrying; successful pushes do not require a
separate remote read-back gate.

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. The selected version must be unused locally and on the
authoritative remote. A version known to have been published elsewhere must
not be reused.

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.

Include a short summary and any relevant compatibility impact or upgrade
instructions. Choose sections suited to the release and keep the note
proportionate to the change. The annotated tag's message is the checked-in note.

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

The publication command validates the final committed candidate once with
ConfigKit's local release checker, using one maintained patch of the minimum
supported Go line on Linux. The checker 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. The
publication command captures the exact candidate and rechecks it after the
validator. A changed candidate requires a fresh invocation and validation.
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

Publication requires authorization before invoking the command. The command
must verify all of the following:

- the stable version has the required format and is unused locally and on the
  authoritative remote;
- the current branch is `main`, and the worktree and index are clean;
- the committed source and matching release note identify the exact validated
  candidate;
- the authoritative remote main can advance to that candidate without
  discarding history;
- the local automated gates succeeded for that commit; and
- the annotated tag identifies that candidate and only the intended refs are
  published.

Push the exact candidate to authoritative main, then create and verify the
annotated tag before pushing only its ref. Do not use `git push --tags` or
implicit follow-tags publication. A failed or ambiguous push receives one
authoritative-state check before success, rejection, or unknown status is
reported.

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 and commit the candidate and
rerun the publication command. If a push fails or its outcome is ambiguous,
inspect the authoritative remote before retrying. Remove an unpublished local
tag only after confirming it was never published or used by a release channel.
An unavailable remote leaves publication status unknown; do not overwrite a tag
to resolve uncertainty. A transient transport failure alone does not require
a new version.

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

Maintain `docs/release.md` as the executable maintainer runbook. It identifies
prerequisites, version and note preparation, the single publication command,
declared deliverables and build targets, successful-tag-push completion, and
partial or unknown-state recovery. Keep optional diagnostics and consumer
verification clearly optional. The procedure must agree with this policy.

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