audita/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/`.
This is an Audita-specific adaptation of the base policy, not a requirement to
implement the standard unchanged. Adapt it further when Audita's needs warrant;
the canonical procedure must agree with the adopted policy.

## Release Model

A release identifies one exact source commit with an immutable version tag and
its checked-in release note. The primary release branch is `main`.

Release success means that the intended version tag has been created and
successfully pushed to the authoritative remote with its source commit. The
release procedure ends at that point. It must never wait for CI to complete or
require successful CI status, artifact publication, or consumer installation as
a completion gate.

CI builds and publishes binaries and checksums asynchronously from the tagged
source. Delayed or failed automation does not reverse release success. Artifact
availability is a separate status and must not be claimed merely because the tag
was pushed. Published artifacts must be traceable to the tagged source.

Automation must not silently change the source candidate, move a published tag,
or replace an existing published artifact.

## Supported Platforms

| Platform | Support |
| --- | --- |
| Linux amd64 | Required production target |
| Linux arm64 | Required production target |
| macOS arm64 | Best effort for local development; failures do not block a release or Linux artifact publication |

Windows and macOS amd64 are unsupported. Neither their builds nor tests are
release requirements. Native macOS testing and access to a Mac are not release
prerequisites.

## 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 on the authoritative
remote 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.

Release notes must contain a short summary and any relevant compatibility or
upgrade instructions. Fixed sections and explicit no-action boilerplate are not
required. Keep notes proportionate to the change.

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

Use the minimum gates needed for confidence in Audita's release. Provide one
local command for the selected automated checks, following the
[testing policy](testing.md). Run the deterministic, offline default test suite
once for the candidate and verify that both required Linux targets build.
Avoid duplicate test runs solely to satisfy separate release phases.

Additional checks must address a concrete risk not already covered. Do not
inherit a mandatory linting, documentation audit, platform matrix, or live-service
checklist solely from the base policy. Documentation migration validation is
separate work, not automatically a recurring release gate.

Automate mechanical guards. Do not require manual approvals, sign-offs, laptop
testing, or post-publication inspection as release gates. Version selection and
a concise release summary remain preparation inputs, not separate approval rounds.

## Publication Guards

The procedure must automate the small set of checks needed to publish the
intended source under a fresh version:

- valid, unused version on the authoritative remote;
- clean worktree and index on the primary release branch;
- the exact candidate that passed the local checks, including its matching note;
- publication of that source commit and the exact intended tag.

Do not require remote CI success. Avoid an additional manual confirmation for
each mechanical guard. Publish explicit refs rather than all local tags.
A successful push is the completion signal; a failed or ambiguous push must be
resolved against remote ref state before declaring success or retrying.

## 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 and commit the candidate, then
rerun the release command. Validation must apply to the exact candidate. An
unpublished local tag may be removed after confirming that it was never published
or used by a release channel.

If a defect is discovered after publication, 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](../release.md) as a short, executable maintainer runbook.
It must identify prerequisites, authoritative remote, version and note preparation,
one local validation command, automated source/tag guards, exact publication
commands, and failure handling. It must name the asynchronous automation and link
to this policy for supported platforms and release-success semantics.

Describe how to diagnose or retry failed artifact delivery separately from release
completion. Missing artifacts may be published later from the same immutable tag;
existing published artifacts must not be overwritten. A source defect requires a
new version. No polling or CI waiting belongs in the release command.

## Audita Adaptations

The maintainer approved these deviations from the base policy on 2026-09-23:

- Audita's needs govern policy adaptation rather than strict template compliance.
- Only Linux amd64 and arm64 are required; macOS arm64 is best effort.
- A successful tag push completes the release; asynchronous CI cannot block it.
- Gates are minimal, automated where practical, and avoid redundant validation
  and human intervention.

The [release procedure](../release.md) and its linked scripts implement these
requirements. CI delivery remains asynchronous.