214 lines
11 KiB
Markdown
214 lines
11 KiB
Markdown
# Release Policy
|
|
|
|
**Base Policy Version:** 1.2
|
|
|
|
**Last Updated:** 2026-09-26
|
|
|
|
## 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.
|
|
|
|
## 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 authoritative publication remote is
|
|
`origin`.
|
|
|
|
A successful push of the intended tag, with its source commit available on the
|
|
authoritative primary branch, completes the release. Publish `main` before
|
|
invoking the publication command; the command requires
|
|
that the remote branch exactly identifies the validated candidate and pushes
|
|
only the selected annotated 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.
|
|
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.
|
|
|
|
Scriptorium publishes Linux binaries and checksums 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.
|
|
|
|
Artifact delivery is a separate status. A successful tag push is not evidence
|
|
that artifacts are available. Delivery failures do not reverse source-release
|
|
success, and optional investigation must not delay release completion.
|
|
|
|
## Versioning And Compatibility
|
|
|
|
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
|
|
no leading zeroes. Prereleases are not part of the adopted release channel.
|
|
|
|
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; 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.
|
|
|
|
## 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. Keep the note proportionate to the change. Fixed sections and
|
|
explicit no-action boilerplate are not required. Existing historical notes
|
|
need not be rewritten to adopt this format.
|
|
|
|
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.
|
|
|
|
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. A release note must not substitute for current documentation.
|
|
Use annotated tags with their message derived from the checked-in note rather
|
|
than requiring a separately authored account of the same release.
|
|
|
|
Version selection, release-note content, and retirement of completed roadmaps
|
|
are preparation responsibilities, not separate human approval gates. Preserve
|
|
planned and deferred work and repair affected links when retiring roadmaps.
|
|
Ordinary change review covers unintended files, credentials, and private data;
|
|
do not repeat it as a release-specific sign-off. Ignored local files are not
|
|
prohibited merely because they exist: they are not included in 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), and 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.
|
|
|
|
The selected test invocation includes the race detector because the HTTP
|
|
service shares engines and backend capacity state across concurrent requests.
|
|
This single invocation covers both ordinary assertions and race detection.
|
|
Build both declared Linux architectures with the hosted release flags to catch
|
|
cross-compilation and packaging failures; native test hardware for each target
|
|
is not required. Existing architecture tests enforce dependency boundaries.
|
|
|
|
Retain narrow source guards against committed workspaces, vendor trees, and
|
|
module replacements: these can otherwise make a passing local build depend on
|
|
unpublished or substituted framework code. Disable workspace discovery and
|
|
vendor mode during validation. These guards preserve the established
|
|
cross-project boundary; they do not require exact dependency-version audits or
|
|
module-metadata rewrites at release time.
|
|
|
|
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 describes
|
|
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;
|
|
- the remote primary branch already identifies that exact candidate; and
|
|
- the tag identifies the validated candidate and only the intended refs are
|
|
published.
|
|
|
|
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,
|
|
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.
|
|
|
|
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
|
|
|
|
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
|
identify:
|
|
|
|
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.
|
|
|
|
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.
|