7.8 KiB
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. 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 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 and its linked scripts implement these requirements. CI delivery remains asynchronous.