Adopt updated release toolchain policy

2026-10-09 04:23:15 +00:00
parent 53b79528d9
commit 08402d098b
3 changed files with 97 additions and 56 deletions
--- a/docs/oss/attribution.md
+++ b/docs/oss/attribution.md
@@ -2,11 +2,12 @@

 ## Standard Repository Policies

-Material: `docs/policy/meta.md`, `docs/policy/oss.md`,
+Material: `docs/policy/release.md`, adapted from
+`e833faddf120c789a9b45348edaf75720de16348`; `docs/policy/meta.md`, `docs/policy/oss.md`,
 `docs/policy/documentation.md`, `docs/policy/agents.md`,
-`docs/policy/architecture.md`, `docs/policy/testing.md`, and
-`docs/policy/release.md`; root `AGENTS.md`; and the Policy Reading Guide in
-`docs/development.md`, adapted for this repository.
+`docs/policy/architecture.md`, `docs/policy/testing.md`; root `AGENTS.md`; and the
+Policy Reading Guide in `docs/development.md`, adapted from
+`d84a38ebab26f048cafbe59a2246700c35d29843` for this repository.

 Copyright (C) 2026 Eric Rakestraw

@@ -14,10 +15,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0

 License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
 [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
-[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE).

 [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).

+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
+
 ## go-yaml v4

 Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
--- a/docs/policy/release.md
+++ b/docs/policy/release.md
@@ -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,
--- a/docs/release.md
+++ b/docs/release.md
@@ -13,7 +13,9 @@ container image, generated package, or separate registry publication.
 - Authoritative push URL: `https://gitea.maximumdirect.net/eric/ConfigKit.git`
 - Tags: stable Semantic Versions such as `v0.5.0`; no prereleases
 - Minimum Go version: the first stable patch of the selected Go series, or a
-  higher patch when required by a dependency or specific correctness fix
+  higher patch when required by a dependency or specific correctness fix, as
+  recorded in `go.mod`; see the
+  [consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain)
 - Release-gated targets: Linux amd64 and arm64
 - Best-effort targets: macOS amd64 and arm64, under the
  [platform support policy](policy/release.md#platform-support)
@@ -25,10 +27,16 @@ not release gates; do not wait for or poll CI.
 ## 1. Select Go and prepare the tool

 Use a clean checkout with Git, Bash 3.2 or newer, and a native compiler for race
-tests. Select the newest stable Go series available in the development
-environment and put its latest locally available compatible patch first on
-`PATH`. The same `go` executable must build ReleaseKit and run its child
-validation commands. Set local toolchain selection and verify it:
+tests. Choose the release type before selecting Go. For a minor or major release,
+select the newest stable Go series available in the development environment.
+For a patch release, retain the series recorded in `go.mod` and leave its consumer
+minimum unchanged. Follow the
+[toolchain selection policy](policy/release.md#configkit-toolchain-selection).
+
+Put the selected series' latest locally available compatible patch first on
+`PATH`, ensuring it meets `go.mod`'s minimum. The same `go` executable must build
+ReleaseKit and run its child validation commands. Set local toolchain selection
+and verify it:

 ```sh
 export GOTOOLCHAIN=local
@@ -37,37 +45,30 @@ go env GOVERSION
 command -v go
 ```

-At release preparation, record the selected series' initial stable release in
-`go.mod`. These commands derive that minimum from the selected executable. The
-calculation preserves a higher patch minimum already recorded within that same
-series; retain it only when dependency or correctness review confirms it is
-still required. Do not keep a higher patch solely because it was previously
-recorded:
+Only when a minor or major release advances the consumer minimum to a newer Go
+series, derive that series' initial stable release from the selected executable:

 ```sh
 selected_go=$(GOTOOLCHAIN=local go env GOVERSION)
 selected_series=${selected_go#go}
 selected_series=${selected_series%.*}
-current_minimum=$(go list -m -f '{{.GoVersion}}')
-release_minimum=$(awk -F. -v current="$current_minimum" -v series="$selected_series" 'BEGIN {
-  split(current, current_parts, "[.]")
-  split(series, selected_parts, "[.]")
-  if (current_parts[1] == selected_parts[1] && current_parts[2] == selected_parts[2] && current_parts[3] + 0 > 0) {
-    print current
-  } else {
-    print series ".0"
-  }
-}')
+release_minimum="$selected_series.0"
 go mod edit -go="$release_minimum"
-go mod download
 ```

-For example, Go 1.26.8 records `go 1.26.0` unless a higher minimum is required.
-The `go` directive is ConfigKit's consumer minimum, not the toolchain pin. A
-minimum increase requires consumers to use the newer Go version; before v1.0.0,
-an intentional compatibility increase requires a minor release under the
-[versioning policy](policy/release.md#versioning-and-compatibility). Review any
-required higher patch minimum as part of compatibility preparation.
+If a dependency or identified correctness fix requires a higher patch minimum,
+use that required version instead and document the reason. When the series is
+unchanged, leave the minimum unchanged unless a minor or major release
+deliberately changes it under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).
+For example, validating with Go 1.26.8 leaves `go 1.26.0` unchanged. There is no
+separate requirement to validate with Go 1.26.0.
+
+Prepare dependencies whether or not the minimum changes:
+
+```sh
+go mod download
+```

 Build the tool selected by `go.mod` into temporary storage outside the checkout.
 Ensure `$TMPDIR` names a system temporary location, not the repository. These
@@ -102,10 +103,9 @@ Choose an unused stable version locally and on the authoritative remote. Compare
 the candidate with the previous tag and review exported Go signatures and
 ownership, YAML and resolution semantics, diagnostic contracts, minimum Go
 version, and platform support. Review maintained consumer examples and the
-migration guidance. Before v1.0.0, a minimum-Go increase that changes the
-compatibility contract requires a minor release and an explanation of consumer
-impact in the release note; patch releases remain compatible within their minor
-line.
+migration guidance. Explain any consumer-minimum increase and required consumer
+action under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).

 Create `docs/releases/<version>.md`. Its first line must be exactly
 `# ConfigKit <version>`, and it must end with the license and attribution footer:
@@ -118,7 +118,7 @@ Replace `VERSION` with the full tag and confirm the three target files exist in
 the candidate. Retire completed roadmaps, preserve unfinished and deferred
 work, and repair affected links. Review the complete candidate for unintended
 files and credentials, then commit it on `main`. These are ordinary preparation
-tasks, not separate approval gates. The `go.mod` change belongs in this
+tasks, not separate approval gates. Any `go.mod` change belongs in this
 candidate.

 ## 3. Push the candidate to `main`