diff --git a/docs/policy/release.md b/docs/policy/release.md index 700361e..dad3083 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,76 +1,79 @@ # 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 This document is the base template for the canonical release policy. Repositories that implement this policy should: -1. Retain the substantive requirements of this policy unless a documented - repository constraint requires an exception; -2. Define the repository-specific release procedure, validation commands, - supported deliverables, and verification commands in `docs/release.md`; -3. Ensure that every document and script required by the adopted policy and - procedure is present on the filesystem; -4. Add stricter repository-specific requirements where the product, delivery - channels, or threat model require them; -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. +1. Adapt its requirements to the application's release needs, keeping gates + minimal and proportionate; +2. Define the repository-specific commands, authoritative remote, primary + branch, supported deliverables, and required build targets in `docs/release.md`; +3. Add a gate only when it addresses a concrete risk that existing checks do + not adequately cover, and record that reason in the adopted policy; +4. Update the `Last Updated` field to the current date; and +5. Remove this heading (`Base Policy Template`) and the associated text. -The base policy is a standard, not a collection of optional recommendations. -An implementing repository should customize its release mechanics without -silently weakening the common integrity, validation, documentation, -verification, or immutability guarantees below. +Do not inherit checks, platform matrices, approval rounds, or documentation +requirements merely because another repository uses them. Simplification does +not require compensating controls for requirements the application does not +need. Changes to an adopted release contract must remain deliberate; agents +must not introduce additional restrictions or guarantees on their own. ## 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/`. -Neither document may weaken this 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 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; -- one immutable version tag identifying that commit; -- one version-matched, checked-in release note; and -- every artifact, image, package, registry entry, or other deliverable the - repository declares for that release. +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. -The repository's primary branch is `main` unless an adopted policy documents -an exception. A release candidate must be committed and pushed to that branch -before its release tag is published. +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. -The source tag is the authoritative release identity. Published deliverables -must be traceable to the tagged source and must agree with its version. A -repository may publish source only. When it publishes additional deliverables, -its release procedure must enumerate them and define how each is built, -identified, published, and verified. +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. -Release automation may validate or publish a release only when its exact -responsibility is documented. Automation must not silently change the source -candidate, move a published tag, replace a published deliverable, or repair a -release in place. +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. Each version must be unused locally and in every configured -remote or publication channel 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`: @@ -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 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/.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/.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. -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 -# vMAJOR.MINOR.PATCH +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. +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 -substantive content. +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. -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. +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. -## Candidate Preparation And Validation - -Each repository must provide one documented release-check command or script -that exercises the complete set of automated source-candidate gates. The -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. +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 -Immediately before publication, the maintainer or release automation must -fetch the current primary branch and tags from the authoritative remote and -verify all of the following: +Automate the checks needed to publish the intended source under a fresh version: -- the version has the required format and is not already published; -- the current branch is the primary release branch; -- the worktree and index are clean; -- the current commit is the recorded, validated candidate; -- the authoritative remote branch points to that same commit; -- the matching release note exists in that commit and has the required title - and sections; -- all required approvals and automated gates succeeded for that commit; and -- no local or remote tag already uses the selected 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 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. -Create the version tag against the guarded commit and verify its target before -publishing it. Publish only the exact intended ref and deliverables. Broad -operations such as `git push --tags` are discouraged because they can publish -unreviewed refs unrelated to the release. +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. -The repository-specific procedure must make these guards executable or give -copyable commands for performing them. +## Immutability And Failure Recovery -## 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, -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 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 validation fails before publication, correct the candidate, rerun the -complete gates, and repeat the publication guards. An unpublished local tag -may be removed after confirming that it was never published or used by a -release channel. +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. -If publication or post-publication verification reveals a defect, 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. +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 -Every adopting repository must maintain `docs/release.md` as the canonical -maintainer runbook for implementing this policy. It must define, in execution -order: +Maintain `docs/release.md` as a short, executable maintainer runbook. It must +identify: -1. maintainer prerequisites and required access; -2. version selection and compatibility review; -3. release-note creation; -4. candidate preparation and the complete validation command; -5. candidate commit, push, and exact commit recording; -6. publication guards; -7. exact tag and deliverable publication commands; -8. authoritative remote and consumer-facing verification; and -9. failure handling and correction. +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. -The procedure should use copyable, fail-fast commands where practical. It must -name the primary branch, authoritative remote, tag form, published -deliverables, supported build targets, release automation responsibilities, -and consumer verification path. It must link to this policy instead of -restating or redefining its requirements. +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.