From e833faddf120c789a9b45348edaf75720de16348 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 03:26:09 +0000 Subject: [PATCH] Clarify release toolchains and Go compatibility requirements --- docs/policy/release.md | 48 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/docs/policy/release.md b/docs/policy/release.md index ddfc5b0..de83dab 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,8 +1,8 @@ # Release Policy -**Base Policy Version:** 1.4 +**Base Policy Version:** 1.6 -**Last Updated**: 2026-09-27 +**Last Updated**: 2026-10-08 ## Base Policy Template @@ -10,8 +10,9 @@ When adopting this policy: 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`; +2. Define the repository-specific commands, release toolchain, 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 @@ -29,6 +30,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. @@ -76,7 +80,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, @@ -88,6 +93,36 @@ 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. + ## Release Documentation And Preparation Every new release must include `docs/releases/.md` in the tagged @@ -203,7 +238,8 @@ release without replacing its contents or reusing its version. Maintain `docs/release.md` as a short, executable maintainer runbook. It must identify: -1. prerequisites, primary branch, and authoritative remote; +1. prerequisites, selected release toolchain, 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;