diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md index 882d8f1..c2920d0 100644 --- a/docs/consumers/delivery.md +++ b/docs/consumers/delivery.md @@ -150,9 +150,11 @@ exit codes, and transport behavior. Use the maintained [tag-delivery workflow](../../examples/woodpecker/tag-delivery.yml) in the consumer repository's `.woodpecker/` directory. Set `GO_IMAGE` to an -image with Go 1.25 or newer, Git, and a local Go version compatible with the -consumer module. It uses `GOTOOLCHAIN=local`; Go does not download a different -toolchain. The tag's `go.mod` must select ReleaseKit as a module dependency. +image with Git and a Go toolchain compatible with the consumer module and its +selected ReleaseKit version. Choose the patch used for the consumer's release +build and validation. The template uses `GOTOOLCHAIN=local`; Go does not download +a different toolchain. The tag's `go.mod` must select ReleaseKit as a module +dependency. Configure the Woodpecker repository secret `releasekit_gitea_token`; the template maps it to `RELEASEKIT_GITEA_TOKEN` for delivery. The repository needs a `delivery` profile. Page-only and binary behavior both use this template; the diff --git a/docs/policy/release.md b/docs/policy/release.md index 0e3464c..1abfdd9 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.4 -**Last Updated**: 2026-10-07 +**Last Updated**: 2026-10-08 **Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) @@ -81,6 +81,35 @@ 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. +## Go Minimum And Release Toolchain + +ReleaseKit provides reasonable support for routine build and release needs, +following [ADR 0002](../adr/0002-routine-releases.md). Its Go support policy relies +on upstream compatibility commitments and verification proportionate to those +needs. + +Select the Go series during release preparation. When advancing the consumer +minimum, use the latest locally available stable series and record its initial +stable version in `go.mod`, such as `go 1.26.0`. Use a higher patch minimum when +a dependency requirement or identified correctness fix requires it. Minimum +increases follow the versioning and compatibility rules above and are explained +in the release note. + +Build the maintainer release executable and validate the candidate with the +same latest locally available patch of the selected series. Keep that toolchain +active throughout preparation, tool bootstrap, and validation, using local +toolchain selection. Maintained CI images follow the chosen build toolchain. +The patch used for these operations is separate from the consumer minimum. + +Successful build and release validation on that patch serve as sufficient +evidence of support from the series' initial stable release through subsequent +patch releases, subject to known dependency requirements or correctness issues. +This relies on Go's [release policy](https://go.dev/doc/devel/release#policy) and +[compatibility commitments](https://go.dev/doc/go1compat). Additional +patch-specific validation is warranted by concrete evidence; routine releases +require no patch-version matrix. Record the actual validation toolchain in the +release evidence. + ## Release Documentation And Preparation Every new release must include `docs/releases/.md` in the tagged diff --git a/docs/release.md b/docs/release.md index 4b7213b..a44a134 100644 --- a/docs/release.md +++ b/docs/release.md @@ -12,8 +12,36 @@ succeeded. CI and consumer installation are not completion checks. ## Prepare a candidate -Use a local Go 1.25 toolchain and a clean clone. Start on `main`, choose an -unused stable `vMAJOR.MINOR.PATCH` version, and add +Use a clean clone on `main`. The chosen build toolchain is Go 1.26.8. Make that +local installation the active `go` command for preparation, building the release +executable, and candidate validation: + +```sh +export GOTOOLCHAIN=local +go version +``` + +Record the reported version with the validation results. The +[Go support policy](policy/release.md#go-minimum-and-release-toolchain) owns +series selection, consumer minima, patch exceptions, and validation scope. +The maintained [source-delivery image](../examples/woodpecker/releasekit-source-delivery.yml) +and [consumer template image](../examples/woodpecker/tag-delivery.yml) follow the +chosen build toolchain; update them together when that selection changes. + +The current consumer minimum is declared in [go.mod](../go.mod). When preparing +a release that raises it to Go 1.26, the normal declaration is: + +```sh +go mod edit -go=1.26.0 +``` + +Retain any higher patch minimum required by dependencies or a specific fix. +Make module changes before committing the candidate. A release preserving the +existing minimum keeps its current declaration. Minimum increases must fit the +[compatibility policy](policy/release.md#versioning-and-compatibility); before +v1.0.0, an increase belongs in a minor release. + +Choose an unused stable `vMAJOR.MINOR.PATCH` version, and add `docs/releases/.md` with a first heading containing `ReleaseKit` and the exact version. Summarize the change and any compatibility or upgrade impact. End the note with the three license links at the immutable source tag: diff --git a/examples/woodpecker/releasekit-source-delivery.yml b/examples/woodpecker/releasekit-source-delivery.yml index 37585cf..393f6fd 100644 --- a/examples/woodpecker/releasekit-source-delivery.yml +++ b/examples/woodpecker/releasekit-source-delivery.yml @@ -4,7 +4,7 @@ when: steps: - name: deliver - image: golang:1.25.0-bookworm + image: golang:1.26.8-bookworm environment: RELEASEKIT_GITEA_TOKEN: from_secret: releasekit_gitea_token diff --git a/examples/woodpecker/tag-delivery.yml b/examples/woodpecker/tag-delivery.yml index 4a624aa..44ce42d 100644 --- a/examples/woodpecker/tag-delivery.yml +++ b/examples/woodpecker/tag-delivery.yml @@ -1,6 +1,6 @@ matrix: include: - - GO_IMAGE: golang:1.25.0-bookworm + - GO_IMAGE: golang:1.26.8-bookworm when: - event: tag