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

Simplify release policy gates and publication workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-25 15:23:55 +00:00
parent 534721cad2
commit 03f9e67088
1 changed files with 152 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

295
docs/policy/release.md
View File

@@ -1,76 +1,79 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.0 **Base Policy Version:** 1.1
**Last Updated**: 2026-09-23 **Last Updated**: 2026-09-25
## Base Policy Template ## Base Policy Template
This document is the base template for the canonical release policy. This document is the base template for the canonical release policy.
Repositories that implement this policy should: Repositories that implement this policy should:
1. Retain the substantive requirements of this policy unless a documented 1. Adapt its requirements to the application's release needs, keeping gates
repository constraint requires an exception; minimal and proportionate;
2. Define the repository-specific release procedure, validation commands, 2. Define the repository-specific commands, authoritative remote, primary
supported deliverables, and verification commands in `docs/release.md`; branch, supported deliverables, and required build targets in `docs/release.md`;
3. Ensure that every document and script required by the adopted policy and 3. Add a gate only when it addresses a concrete risk that existing checks do
procedure is present on the filesystem; not adequately cover, and record that reason in the adopted policy;
4. Add stricter repository-specific requirements where the product, delivery 4. Update the `Last Updated` field to the current date; and
channels, or threat model require them; 5. Remove this heading (`Base Policy Template`) and the associated text.
5. Record every exception under `Policy Exceptions`, including its rationale
and compensating controls;
6. Update the `Last Updated` field to the current date; and
7. Remove this heading (`Base Policy Template`) and the associated text.
The base policy is a standard, not a collection of optional recommendations. Do not inherit checks, platform matrices, approval rounds, or documentation
An implementing repository should customize its release mechanics without requirements merely because another repository uses them. Simplification does
silently weakening the common integrity, validation, documentation, not require compensating controls for requirements the application does not
verification, or immutability guarantees below. need. Changes to an adopted release contract must remain deliberate; agents
must not introduce additional restrictions or guarantees on their own.
## Purpose ## Purpose
This policy defines the minimum requirements for selecting, validating, This policy defines a proportionate workflow for validating and publishing an
publishing, verifying, and correcting releases. Its goal is to make every intended source revision under a fresh version. Releases should require little
release intentional, reproducible from an exact source revision, documented routine intervention, avoid repeated work, and preserve published contents.
for consumers, and safe from retrospective replacement.
The repository-specific commands that implement these requirements belong in The repository-specific commands belong in `docs/release.md`. Historical release
`docs/release.md`. Historical release summaries belong in `docs/releases/`. summaries belong in `docs/releases/`. The procedure must agree with the adopted
Neither document may weaken this policy. policy and link to it rather than introduce additional release requirements.
## Release Model ## Release Model And Completion
A release consists of: 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.
- one exact source commit reachable from the repository's primary branch; A successful push of the intended tag, with its source commit available on the
- one immutable version tag identifying that commit; authoritative primary branch, completes the release. The source commit may be
- one version-matched, checked-in release note; and pushed before the tag or published together with it through an atomic push.
- every artifact, image, package, registry entry, or other deliverable the The procedure must choose and document the supported approach.
repository declares for that release.
The repository's primary branch is `main` unless an adopted policy documents Release commands must finish at successful publication. They must not wait for
an exception. A release candidate must be committed and pushed to that branch or poll CI, require successful CI status, inspect downloadable artifacts, or
before its release tag is published. 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.
The source tag is the authoritative release identity. Published deliverables Repositories may publish source only. Additional binaries, images, packages,
must be traceable to the tagged source and must agree with its version. A checksums, or other declared deliverables may be published asynchronously from
repository may publish source only. When it publishes additional deliverables, the tagged source. The procedure must identify those deliverables and the
its release procedure must enumerate them and define how each is built, responsibility of their automation. Published deliverables must be traceable
identified, published, and verified. to that source and identify the same version.
Release automation may validate or publish a release only when its exact Artifact delivery is a separate status. A successful tag push is not evidence
responsibility is documented. Automation must not silently change the source that artifacts are available. Delivery failures do not reverse source-release
candidate, move a published tag, replace a published deliverable, or repair a success, and optional investigation must not delay release completion.
release in place.
## Versioning And Compatibility ## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. Each version must be unused locally and in every configured no leading zeroes. Prereleases require an explicit adopted policy defining
remote or publication channel before publication begins. their format and use.
Unless an adopted policy explicitly supports and defines prereleases, The selected version must be unused locally and on the authoritative remote.
prerelease versions are not permitted. 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`: For releases at or after `v1.0.0`:
@@ -83,125 +86,131 @@ configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must note explains the impact and required consumer action. A patch release must
not intentionally break those contracts within its minor line. not intentionally break those contracts within its minor line.
A repository with additional compatibility promises must define them in its Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. A release note may explain adopted policy or canonical contract documentation. Release notes explain
a compatibility change, but it must not redefine the current compatibility changes; they do not redefine current compatibility contracts.
contract.
## Release Documentation ## Release Documentation And Preparation
Every release made under this policy must include Every new release must include `docs/releases/<version>.md` in the tagged
`docs/releases/<version>.md` in the tagged source tree. The filename must use source tree. Use the complete version tag as the filename and begin with a
the complete version tag, and the document must begin with a title containing title containing the product name and that exact version.
the product name and that exact version.
Every new release note must contain these sections: 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.
```markdown Keep exact current contracts in their canonical documents and update affected
# <Product> vMAJOR.MINOR.PATCH documentation with the behavior change. Link to those documents from the note
where useful. A release note must not substitute for current documentation.
If annotated tags are used, derive their summary from the checked-in note
rather than requiring a separately authored account of the same release.
This 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.
## Summary ## Candidate Validation
## Compatibility 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.
## Upgrade 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.
## Changes 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.
Use an explicit statement such as "No action required" when a section has no Release tests must not require real credentials, mutable application services,
substantive content. paid APIs, provider probes, or inference calls. The procedure may describe dependency
preparation separately from offline validation.
Release notes are immutable historical summaries. They should link to current Avoid duplicate validation across release phases. Successful checks for the
canonical documentation for exact behavior. Every affected canonical document same final candidate need not be repeated solely to satisfy another phase;
must be updated in the same candidate; a release note must not substitute for any reuse must clearly apply to that exact candidate. Persistent validation
current documentation or defer required documentation changes. 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.
## Candidate Preparation And Validation Automate mechanical guards. Human review gates are strongly disfavored: add one
only through an explicit project-specific policy decision explaining the
Each repository must provide one documented release-check command or script concrete risk and why ordinary change review or automation is insufficient.
that exercises the complete set of automated source-candidate gates. The Do not add routine confirmations for checks the command can perform itself.
repository-specific procedure must state all additional manual gates.
The required gates are:
- dependency or module hygiene appropriate to the language and ecosystem;
- the complete deterministic, offline default test suite;
- static analysis and linting used by the repository;
- formatting and whitespace checks;
- validation of maintained examples, configuration, schemas, generated
sources, and documentation commands where applicable;
- review of changed local documentation links;
- removal of obsolute roadmap documents under `docs/roadmap/` that describe
completed work included in the release; and
- review for unintended files, generated output, credentials, private data,
and unrelated changes.
## Publication Guards ## Publication Guards
Immediately before publication, the maintainer or release automation must Automate the checks needed to publish the intended source under a fresh version:
fetch the current primary branch and tags from the authoritative remote and
verify all of the following:
- the version has the required format and is not already published; - the version has the adopted format and is unused locally and on the
- the current branch is the primary release branch; authoritative remote;
- the worktree and index are clean; - the worktree and index are clean on the primary release branch;
- the current commit is the recorded, validated candidate; - the source being published is the exact candidate that passed validation,
- the authoritative remote branch points to that same commit; including its matching release note;
- the matching release note exists in that commit and has the required title - the remote primary branch already identifies that candidate, or an atomic
and sections; source/tag push will advance it to that candidate without discarding remote
- all required approvals and automated gates succeeded for that commit; and history; and
- no local or remote tag already uses the selected version. - the tag identifies the validated candidate and only the intended refs are
published.
Create the version tag against the guarded commit and verify its target before Fetch the authoritative branch and tag state as needed for these checks.
publishing it. Publish only the exact intended ref and deliverables. Broad Do not force branch or tag updates to bypass a failed guard. Publish explicit
operations such as `git push --tags` are discouraged because they can publish refs rather than all local tags. Do not require CI success, publication-service
unreviewed refs unrelated to the release. availability checks, or a separate manual confirmation for each guard.
The repository-specific procedure must make these guards executable or give ## Immutability And Failure Recovery
copyable commands for performing them.
## Immutability And Correction 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.
Published version tags and published deliverables are immutable. Do not move, If validation fails before publication, correct and commit the candidate and
overwrite, recreate, or delete a published tag. Do not replace an artifact, rerun the publication command. If a push fails or its outcome is ambiguous,
image, package, checksum, signature, provenance statement, or release note inspect the authoritative remote before retrying. Remove an unpublished local
under an already published version. 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 validation fails before publication, correct the candidate, rerun the Transient network, authentication, CI, or consumer-availability failures do not
complete gates, and repeat the publication guards. An unpublished local tag by themselves require a new version. Asynchronous delivery may be retried from
may be removed after confirming that it was never published or used by a the same immutable tag. Missing artifacts may be published later, provided
release channel. 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.
If publication or post-publication verification reveals a defect, leave the A defect requiring changes to published source or contents requires a corrected
published release intact. Correct the defect on the primary branch, choose a commit, a new semantically appropriate version, a matching release note, and
new patch version or other semantically appropriate new version, write a new the release procedure again. Leave the original release intact. A channel's
matching release note, and perform the complete release procedure again. yank, deprecation, or advisory mechanism may warn consumers away from a defective
release without replacing its contents or reusing its 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.
## Repository Release Procedure ## Repository Release Procedure
Every adopting repository must maintain `docs/release.md` as the canonical Maintain `docs/release.md` as a short, executable maintainer runbook. It must
maintainer runbook for implementing this policy. It must define, in execution identify:
order:
1. maintainer prerequisites and required access; 1. prerequisites, primary branch, and authoritative remote;
2. version selection and compatibility review; 2. version and release-note preparation;
3. release-note creation; 3. one publication command with its selected local checks and automated guards;
4. candidate preparation and the complete validation command; 4. declared deliverables, required build targets, and automation responsibilities;
5. candidate commit, push, and exact commit recording; 5. the successful-push completion point and separately reported delivery status;
6. publication guards; and
7. exact tag and deliverable publication commands; 6. failure handling, ambiguous-push recovery, and asynchronous delivery retries.
8. authoritative remote and consumer-facing verification; and
9. failure handling and correction.
The procedure should use copyable, fail-fast commands where practical. It must Use copyable commands where practical. Keep optional diagnostics and consumer
name the primary branch, authoritative remote, tag form, published verification clearly optional. The procedure must not turn preparation work,
deliverables, supported build targets, release automation responsibilities, ordinary change review, or post-publication investigation into additional
and consumer verification path. It must link to this policy instead of release gates.
restating or redefining its requirements.