eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Adopt remaining policies and selective reading guide

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:07:03 +00:00
parent 9723102117
commit edbbf3d5ea
10 changed files with 491 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/policy/release.md
View File

@@ -1,40 +1,47 @@
# Release Policy
**Base Policy Version:** 1.0
**Base Policy Version:** 1.4
**Last Updated**: 2026-09-23
**Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
## 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.
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 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.
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.
## Release Model
## Release Model And Completion
A release identifies one exact source commit with an immutable version tag and
its checked-in release note. The primary release branch is `main`.
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` unless the adopted policy specifies otherwise.
The procedure must name the authoritative publication remote.
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.
A successful push of the intended tag, with its source commit available on the
authoritative primary branch, completes the release. The source commit may be
pushed before the tag or published together with it through an atomic push.
The procedure must choose and document the supported approach.
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.
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.
Automation must not silently change the source candidate, move a published tag,
or replace an existing published artifact.
Repositories may publish source only. Additional binaries, images, packages,
checksums, or other declared deliverables may be published asynchronously from
the tagged source. The procedure must identify those deliverables and the
responsibility of their automation. Published deliverables must be traceable
to that source and identify the same version.
Track source-release completion and artifact delivery separately. Report delivery
failures and optional investigations under artifact-delivery status.
## Supported Platforms
@@ -51,11 +58,14 @@ 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.
no leading zeroes. Prereleases require an explicit adopted policy defining
their format and use.
Unless an adopted policy explicitly supports and defines prereleases,
prerelease versions are not permitted.
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`:
@@ -68,101 +78,133 @@ 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.
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.
## Release Documentation
## Release Documentation And Preparation
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 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.
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.
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.
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.
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. If annotated tags are used, derive their summary from the
checked-in note.
## Candidate Preparation And Validation
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.
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.
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.
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.
## Candidate Validation
Automate mechanical guards. Do not require manual approvals, sign-offs, laptop
testing, or post-publication inspection as release gates. Version selection and
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 application's actual support commitments; native testing on each platform
and access to particular hardware are not default release prerequisites.
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, provider 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. Do not require manual approvals, sign-offs, or
routine confirmations 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:
Automate the 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.
- 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;
- the remote primary branch already identifies that candidate, or an atomic
source/tag push will advance it to that candidate without discarding remote
history; and
- the tag identifies the validated candidate and only the intended refs are
published.
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.
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 Correction
## Immutability And Failure Recovery
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.
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, 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 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.
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.
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 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.
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
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.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify:
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.
1. prerequisites, 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.
## 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.
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.