ReleaseKit/docs/policy/release.md

# Release Policy

**Base Policy Version:** 1.6

**Last Updated**: 2026-10-08

**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/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.

Adopt stronger verification or reproducibility requirements through an explicit
project-specific decision justified by the intended audience and support needs.

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.

This policy governs releases of ReleaseKit itself. Go declarations and GoDoc
own supported consumer API contracts. The maintainer runbook describes
ReleaseKit's implemented source publication and hosted-page delivery procedure.

## Release Model And Completion

A source release identifies one exact committed source revision through an
immutable version tag and a version-matched, checked-in release note. The
primary release branch is `main`.
The procedure must name the authoritative publication remote.

A successful push of the intended annotated tag, with its source commit already
published on authoritative `main`, completes the release. The remote branch must
identify the validated candidate before the command publishes only the exact
intended tag object. The [maintainer runbook](../release.md) identifies the
authoritative endpoint and command.

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

ReleaseKit's deliverables are its immutable source tag and a hosted Gitea
release page whose body is the complete checked-in release note. A prepared
Woodpecker workflow builds the local release tool from that tagged source and
delivers the note page. This adds no executable download or binary manifest.
Any later distribution of executable builds requires a deliberate update
identifying the deliverables, selected targets, and automation responsibilities.
Supporting cross-builds for consumers does not declare ReleaseKit binaries.
Additional declared deliverables may be published asynchronously from the
tagged source, must be traceable to that source, and must identify the same
version.

Track source-release completion and artifact delivery separately. Report delivery
failures and optional investigations under artifact-delivery status.

## Versioning And Compatibility

Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. Prereleases require an explicit adopted policy defining
their format and use.

The selected version must be unused locally and on the authoritative remote.
Do not require queries to every configured remote or publication service.
A version known to have already been published must not be reused, even if the
normal guards do not inspect that channel. Adding a distribution channel
requires a deliberate update to the policy and procedure where needed.

For releases at or after `v1.0.0`:

- a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior or raise the Go consumer
  minimum as described below; 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.

Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts.

## Consumer Minimum And Release Toolchain

ReleaseKit provides reasonable support for routine build and release needs,
following [ADR 0002](../adr/0002-routine-releases.md). Distinguish the minimum Go
toolchain supported for consumers from the toolchain maintainers use to build
and validate a release. The consumer minimum belongs in [go.mod](../../go.mod);
the [maintainer runbook](../release.md) defines the selected release toolchain
and its setup commands.

Select the Go series during release preparation. When advancing the consumer
minimum, use the latest locally available stable series and record its initial
stable version in `go.mod`, such as `go 1.26.0`. Use a higher patch minimum when
a dependency requirement or identified correctness fix requires it, and document
the reason.

Build the maintainer release executable and validate the candidate with the
same latest locally available patch of the selected series. Keep that toolchain
active throughout preparation, tool bootstrap, and validation, using local
toolchain selection. CI jobs performing release builds and validation use the
selected toolchain; maintained CI images follow that choice. A newer validation
patch version alone leaves the consumer minimum unchanged.

For release-policy purposes, successful build and release validation on that
patch are sufficient to presume support across the selected Go series, subject
to the declared consumer minimum and concrete evidence of incompatibility.
This relies on Go's [release policy](https://go.dev/doc/devel/release#policy) and
[compatibility commitments](https://go.dev/doc/go1compat). Investigate specific
compatibility concerns as they arise. Routine releases require no patch-version
matrix. Record the actual validation toolchain in the release evidence.

A minor release may raise the Go consumer minimum, including from one Go series
to the next, both before and after `v1.0.0`. This is an explicit exception to the
backward-compatibility requirement for minor releases. Patch releases preserve
the consumer minimum. Explain an increase's impact and required consumer action
in the release note. Other incompatible changes remain subject to the versioning
rules above.

## Release Documentation And Preparation

Every new release must include `docs/releases/<version>.md` in the tagged
source tree. Use the complete version tag as the filename and 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.

Keep exact current contracts in their canonical documents and update affected
documentation with the behavior change. Link to those documents from the note
where useful. Derive the annotated tag's message from the checked-in note.

Include the release footer defined by the [OSS policy](oss.md#discoverability)
in each new release document and preserve it on the hosted download page. The
release procedure defines the concrete URLs and publication mechanics. Prepare
these links with the release note; they do not add a network check or approval
gate.

Handle version selection, release-note content, and retirement of completed
roadmaps during preparation. Preserve planned and deferred work and repair
affected links when retiring roadmaps. Reuse ordinary change review for
unintended files, credentials, and private data. Scope release-content review
to the tagged source.

## Candidate Validation

Provide one publication command that validates the final committed candidate,
checks publication state, and publishes the intended refs. A validation-only
mode or command may be provided for diagnosis, but must not be a required step
before publication repeats the same checks.

Run the complete deterministic, offline default test suite once for the final
candidate, following the [testing policy](testing.md). For repositories that
publish builds, verify the required build targets. Select those targets for
the project's actual support commitments; native testing on each platform
and access to particular hardware are not default release prerequisites.

The publication command runs the standard offline Go test suite, followed by
any additional product checks. The [maintainer runbook](../release.md) owns its
invocation. ReleaseKit's source-only deliverable adds no binary target matrix.

Additional gates must address a concrete risk that the existing checks do not
adequately cover. Do not automatically require linting, race testing, module
hygiene audits, documentation audits, credential scans, example validation, or
expanded platform matrices solely because they are possible. Retain such
checks when their distinct protection justifies their cost. A one-time migration
check must not silently become a permanent release requirement.

Release tests must not require real credentials, mutable application services,
paid APIs, live service probes, or inference calls. The procedure may describe
dependency preparation separately from offline validation.

Avoid duplicate validation across release phases. Successful checks for the
same final candidate need not be repeated solely to satisfy another phase;
any reuse must clearly apply to that exact candidate. Persistent validation
caches are not required. If the candidate changes, validate the new candidate.
Cheap publication-state checks may be repeated immediately before pushing
because local or remote state may have changed during validation.

Automate mechanical guards. Human review gates are strongly disfavored: add one
only through an explicit project-specific policy decision explaining the
concrete risk and why ordinary change review or automation is insufficient.
Do not add routine confirmations for checks the command can perform itself.

## Publication Guards

Automate the checks needed to publish the intended source under a fresh version:

- the version has the adopted format and is unused locally and on the
  authoritative remote;
- the worktree and index are clean on the primary release branch;
- the source being published is the exact candidate that passed validation,
  including its matching release note;
- authoritative `main` already identifies that candidate; and
- the annotated tag identifies the validated candidate and only its exact object
  is published through an explicit tag ref.

Fetch the authoritative branch and tag state as needed for these checks.
Do not force branch or tag updates to bypass a failed guard. Publish explicit
refs rather than all local tags. Do not require CI success, publication-service
availability checks, or a separate manual confirmation for each guard.

## Immutability And Failure Recovery

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,
query the authoritative tag ref once. Confirm success only when it identifies
the exact intended tag object on the validated commit; otherwise report failed
or unknown status and retain the local tag. Resolve that authoritative state
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.

Transient network, authentication, CI, or consumer-availability failures do not
by themselves require a new version. Asynchronous delivery may be retried from
the same immutable tag. Missing artifacts may be published later, provided
existing published contents are not replaced and the additions remain consistent
with the tagged source and any already-published checksum manifest. If that
cannot be achieved, publish a new version.

A defect requiring changes to published source or contents requires a corrected
commit, a new semantically appropriate version, a matching release note, and
the release procedure again. Leave the original release intact. A channel's
yank, deprecation, or advisory mechanism may warn consumers away from a defective
release without replacing its contents or reusing its version.

## Repository Release Procedure

Create and maintain `docs/release.md` with the first working publication command
as a short, executable maintainer runbook. It must identify:

1. prerequisites, selected release toolchain, primary branch, and authoritative
   remote;
2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards;
4. declared deliverables, required build targets, and automation responsibilities;
5. the successful-push completion point and separately reported delivery status;
   and
6. failure handling, ambiguous-push recovery, and asynchronous delivery retries.

Use copyable commands where practical. Keep optional diagnostics and consumer
verification clearly optional. The procedure must not turn preparation work,
ordinary change review, or post-publication investigation into additional
release gates.