From 5aafd943b44fd695c8381c54062226d0e5296c00 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 8 Oct 2026 13:33:43 +0000 Subject: [PATCH] Plan Go toolchain updates for releases --- docs/roadmap/releasekit.md | 51 +++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 7fa4838..bb48280 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -47,13 +47,20 @@ best effort. ReleaseKit's other optional checks, including formatting, Markdown, module-distribution, and file-size checks, remain unselected unless a separate decision establishes a distinct need for them. -The release tool is selected at a known version and prepared before offline -candidate validation. The `go` executable used by ReleaseKit must be a -maintained Go 1.25 patch with native race prerequisites available: ReleaseKit -sets `GOTOOLCHAIN=local` for its child commands, so ConfigKit's existing -`CONFIGKIT_BASELINE_TOOLCHAIN` environment selection cannot serve as the -validation mechanism. Dependency and tool preparation may use the network; -candidate validation remains offline and readonly. +At each release preparation, select the newest Go version available in the +development environment and advance ConfigKit's `go.mod` `go` directive to +that version. This deliberately raises ConfigKit's minimum Go version for +consumers when the selected version is newer. Use the same selected Go +executable to build the pinned ReleaseKit tool and to run ReleaseKit's +validation, with native race prerequisites available. ReleaseKit sets +`GOTOOLCHAIN=local` for its child commands, so ConfigKit's existing +`CONFIGKIT_BASELINE_TOOLCHAIN` environment selection cannot select a +different validation toolchain. Prepare the tool and dependencies before +offline candidate validation; the `go.mod` change belongs in the committed +candidate. Review any minimum-Go increase as a compatibility change and +explain its consumer impact in the release note. Before v1.0.0, an intentional +increase requires a minor rather than patch release under ConfigKit's +[versioning policy](../policy/release.md#versioning-and-compatibility). ReleaseKit owns generic candidate guards, test and compile coordination, tag creation, publication, and push recovery. ConfigKit owns version selection, @@ -64,14 +71,16 @@ release process adds no ConfigKit public API or runtime use of ReleaseKit. ## Changes from the baseline - Add the minimal profile and a documented, versioned tool-preparation method. - Keep the selected release command small and do not re-create generic Git - guards or Go check sequencing in a wrapper. + The release runbook should select the newest Go available in the development + environment, advance `go.mod`, and build ReleaseKit with that same Go + executable. Keep the selected release command small and do not re-create + generic Git guards or Go check sequencing in a wrapper. - Revise the [release policy](../policy/release.md) and [maintainer procedure](../release.md) for candidate publication to `main` - before ReleaseKit's command, its effective-push-URL check, toolchain - preparation, one selected validation pass, tag-only publication, and - ReleaseKit's failure states. Preserve ConfigKit's source-only deliverables, - compatibility rules, supported targets, and no-CI completion rule. + before ReleaseKit's command, its effective-push-URL check, recurring Go + version selection and compatibility review, one selected validation pass, + tag-only publication, and ReleaseKit's failure states. Preserve ConfigKit's + source-only deliverables, supported targets, and no-CI completion rule. - Update the [development guide](../development.md) so its release guidance and task-to-test map describe the adopted process. Keep ordinary development checks separate from release gates; review other references to the retired @@ -84,8 +93,9 @@ release process adds no ConfigKit public API or runtime use of ReleaseKit. - Verify the migration without publishing a real ConfigKit version: exercise the selected profile and release command against an isolated candidate and temporary Git remote, including a validation failure and successful tag - publication. Confirm the maintained Go 1.25 patch runs the selected gates - once. Do not make a separate successful CI run a release condition. + publication. Confirm that the selected Go executable matches the candidate's + `go.mod` directive, builds ReleaseKit, and runs the selected gates once. Do + not make a separate successful CI run a release condition. Historical tags and release notes remain unchanged. This adoption work does not itself authorize publication of a ConfigKit version. @@ -95,11 +105,12 @@ not itself authorize publication of a ConfigKit version. ### How should ConfigKit pin and acquire ReleaseKit? **Recommendation:** Use a separately installed ReleaseKit executable pinned to -v0.2.0 for the first migration, and document acquisition before offline -validation. ConfigKit has no hosted-delivery workflow to coordinate with a CI -tool pin, so this keeps ReleaseKit and its tool dependencies out of ConfigKit's -library module graph. The [OSS policy](../policy/oss.md) does not require an -attribution entry merely for using a development tool. +v0.2.0 for the first migration, built with the Go version selected during +release preparation. Document acquisition before offline validation. ConfigKit +has no hosted-delivery workflow to coordinate with a CI tool pin, so this +keeps ReleaseKit and its tool dependencies out of ConfigKit's library module +graph. The [OSS policy](../policy/oss.md) does not require an attribution entry +merely for using a development tool. **Viable alternative:** Declare ReleaseKit in ConfigKit's `go.mod` and use its module-selected tooling convention. This gives local publication and any future