Adopt updated release toolchain policy
This commit is contained in:
@@ -1,10 +1,10 @@
|
||||
# Release Policy
|
||||
|
||||
**Base Policy Version:** 1.4
|
||||
**Base Policy Version:** 1.6
|
||||
|
||||
**Last Updated**: 2026-09-28
|
||||
**Last Updated**: 2026-10-09
|
||||
|
||||
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
|
||||
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -12,6 +12,9 @@ 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.
|
||||
|
||||
Adopt stronger verification or reproducibility requirements through an explicit
|
||||
project-specific decision justified by the intended audience and support needs.
|
||||
|
||||
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.
|
||||
@@ -98,7 +101,8 @@ 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 minor release may add backward-compatible behavior or raise the Go consumer
|
||||
minimum as described below; and
|
||||
- a patch release may make backward-compatible fixes.
|
||||
|
||||
Before `v1.0.0`, a minor release may change a documented public, operational,
|
||||
@@ -110,6 +114,45 @@ 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.
|
||||
|
||||
## Consumer Minimum And Release Toolchain
|
||||
|
||||
Distinguish the minimum toolchain supported for consumers from the toolchain
|
||||
maintainers use to build and validate a release. Record the consumer minimum in
|
||||
the language's standard metadata and explain its support meaning in canonical
|
||||
documentation. Define the selected release toolchain and its setup commands in
|
||||
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
|
||||
choices.
|
||||
|
||||
For Go repositories, normally declare the initial stable release of the selected
|
||||
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
|
||||
when a dependency or an identified correctness fix requires it, and document
|
||||
the reason.
|
||||
|
||||
For release-policy purposes, successful build and release validation on the
|
||||
selected Go patch release are sufficient to presume support across that Go
|
||||
series, subject to the declared consumer minimum and concrete evidence of
|
||||
incompatibility. Investigate specific compatibility concerns as they arise.
|
||||
|
||||
Use the selected release toolchain for candidate validation and release builds,
|
||||
including CI jobs performing those tasks. A newer validation patch version alone
|
||||
leaves the consumer minimum unchanged.
|
||||
|
||||
A minor release may raise the Go consumer minimum, including from one Go series
|
||||
to the next, both before and after `v1.0.0`. This is an explicit exception to the
|
||||
backward-compatibility requirement for minor releases. Patch releases preserve
|
||||
the consumer minimum. Explain an increase's impact and required consumer action
|
||||
in the release note. Other incompatible changes remain subject to the versioning
|
||||
rules above.
|
||||
|
||||
### ConfigKit Toolchain Selection
|
||||
|
||||
For minor and major releases, select the newest stable Go series available in
|
||||
the development environment. For patch releases, retain the series recorded in
|
||||
`go.mod` and its consumer minimum. Use the latest locally available compatible
|
||||
patch in the selected series, with `GOTOOLCHAIN=local`, to build the
|
||||
module-selected ReleaseKit CLI and validate the candidate. The same Go
|
||||
executable builds the tool and runs its validation commands.
|
||||
|
||||
## Release Documentation And Preparation
|
||||
|
||||
Every new release must include `docs/releases/<version>.md` in the tagged
|
||||
@@ -159,16 +202,9 @@ 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.
|
||||
|
||||
For release preparation, record the initial stable release of the newest
|
||||
locally available Go series in `go.mod`'s `go` directive. Retain a higher patch
|
||||
minimum only when required by a dependency or a specific correctness fix. Use
|
||||
the latest locally available compatible patch in that series, selected with
|
||||
`GOTOOLCHAIN=local`, to build the module-selected ReleaseKit CLI and validate the
|
||||
candidate, provided it meets the current `go.mod` minimum. Review any
|
||||
minimum-version increase under the existing compatibility rules. Prepare
|
||||
dependencies and build the tool before offline validation; the publication
|
||||
command is the required validation run, with no separate successful test or CI
|
||||
run required before it.
|
||||
Prepare dependencies and build the tool before offline validation; the
|
||||
publication command is the required validation run, with no separate successful
|
||||
test or CI run required before it.
|
||||
|
||||
The selected profile runs the complete deterministic, offline default suite
|
||||
once with the race detector and test-time vet disabled. The suite already
|
||||
@@ -265,10 +301,10 @@ 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 prerequisites, the primary branch and authoritative remote, version
|
||||
and note preparation, one publication command with local checks and guards,
|
||||
source-only deliverables, the successful-tag-push completion point, and
|
||||
partial or unknown-state recovery.
|
||||
identify prerequisites, the selected release toolchain, the primary branch and
|
||||
authoritative remote, version and note preparation, one publication command with
|
||||
local checks and guards, source-only deliverables, the successful-tag-push
|
||||
completion point, and partial or unknown-state recovery.
|
||||
|
||||
Use copyable commands where practical. Keep optional diagnostics and consumer
|
||||
verification clearly optional. The procedure must not turn preparation work,
|
||||
|
||||
Reference in New Issue
Block a user