Adopt updated release toolchain policy

This commit is contained in:
2026-10-09 04:23:15 +00:00
parent 53b79528d9
commit 08402d098b
3 changed files with 97 additions and 56 deletions

View File

@@ -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`