eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Separate Go minimum from release toolchain

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-08 16:23:25 +00:00
parent c42930c6d5
commit 0ac4731903
2 changed files with 59 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/roadmap/implementation.md
View File

@@ -9,17 +9,18 @@ current release procedure authoritative until the replacement is working.
Follow the task-specific reading guide in [development.md](../development.md) Follow the task-specific reading guide in [development.md](../development.md)
and avoid adding gates, compatibility promises, or restrictions beyond the and avoid adding gates, compatibility promises, or restrictions beyond the
roadmap and adopted policies. Stages 3–5 are one documentation-and-machinery roadmap and adopted policies. Stages 3–5 are one documentation-and-machinery
cutover; their intermediate state is not a release candidate. cutover; do not commit or hand off their intermediate state as a release-ready
candidate.
## Stage 1: Select Go and declare the release tool ## Stage 1: Select Go and declare the release tool
1. Identify the newest Go executable available in the development environment 1. Identify the latest locally available patch in the newest stable Go series
when implementing this stage. Make it the `go` on `PATH`, verify it with available in the development environment. Make it the `go` on `PATH` and
`GOTOOLCHAIN=local go version`, and advance ConfigKit's `go.mod` `go` verify it with `GOTOOLCHAIN=local go version`. Keep ConfigKit's current
directive to its full version. Do not substitute a newer downloaded `go.mod` `go` minimum until the release-workflow cutover in Stage 4: the
toolchain during later validation. Record the resulting minimum-Go increase existing release checker still selects Go 1.25 and cannot validate a module
for the next release's compatibility review; before v1.0.0, an intentional requiring Go 1.26. Do not substitute an automatically downloaded toolchain
increase requires a minor release, not a patch release. during later validation.
2. Using that same Go executable, add 2. Using that same Go executable, add
`gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0` as a `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0` as a
`go.mod` tool dependency (the Go `tool` directive and its module `go.mod` tool dependency (the Go `tool` directive and its module
@@ -34,10 +35,13 @@ cutover; their intermediate state is not a release candidate.
[OSS policy](../policy/oss.md); a tool used only for development and release [OSS policy](../policy/oss.md); a tool used only for development and release
work does not by itself require an attribution entry. work does not by itself require an attribution entry.
Completion evidence: `go.mod` selects the chosen Go version and the pinned Completion evidence: `go.mod` retains its current Go minimum and selects the
ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no unintended pinned ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no
changes, the module-selected executable builds with the selected Go, and the unintended changes, the module-selected executable builds with the selected
ordinary offline Go suite still passes after dependencies are prepared. local Go, and the ordinary offline Go suite still passes after dependencies
are prepared. If the new tool dependency itself requires a higher minimum,
handle that compatibility change together with the cutover rather than
leaving the current release checker unusable.
## Stage 2: Add ConfigKit's ReleaseKit profile ## Stage 2: Add ConfigKit's ReleaseKit profile
@@ -70,8 +74,11 @@ delivery configuration.
baseline with the selected local Go executable, the current `go.mod` baseline with the selected local Go executable, the current `go.mod`
minimum, the module-selected ReleaseKit CLI, its one race suite with minimum, the module-selected ReleaseKit CLI, its one race suite with
test-time vet disabled, full vet, and Linux amd64/arm64 package compilation. test-time vet disabled, full vet, and Linux amd64/arm64 package compilation.
State that preparation advances `go.mod` to the newest Go available in the State that preparation records the initial stable release of the newest
development environment and reviews any minimum-version increase under locally available Go series in `go.mod`, retaining a higher patch minimum
only when required by a dependency or specific correctness fix. Use the
latest locally available compatible patch in that series for ReleaseKit's
build and validation, and review any minimum-version increase under
existing compatibility rules. Keep dependency acquisition and tool build existing compatibility rules. Keep dependency acquisition and tool build
before offline candidate validation; do not add a separate successful test before offline candidate validation; do not add a separate successful test
or CI run as a publication prerequisite. or CI run as a publication prerequisite.
@@ -89,16 +96,21 @@ stronger automated guards as current behavior.
## Stage 4: Replace the maintainer release runbook ## Stage 4: Replace the maintainer release runbook
1. Revise [the runbook](../release.md) into copyable steps for the adopted 1. Revise [the runbook](../release.md) into copyable steps for the adopted
process. During preparation, select the newest Go executable available in process. During this cutover, move `go.mod` from its current minimum to the
the development environment, keep it first on `PATH`, verify its version first stable release of the newest Go series available in the development
with `GOTOOLCHAIN=local`, and update `go.mod` to that full version if needed. environment (for example, `go 1.26.0` when using Go 1.26.8), unless a
dependency or specific correctness fix needs a higher patch minimum. Have
the runbook derive the series from `GOTOOLCHAIN=local go env GOVERSION` and
use `go mod edit` to record its `.0` release, without lowering an existing
required higher patch minimum. Keep that series' latest locally available
compatible patch first on `PATH` for both the tool build and validation.
Explain the minimum-Go compatibility impact and version choice, including Explain the minimum-Go compatibility impact and version choice, including
the pre-v1.0.0 minor-release rule. Prepare dependencies, then build the the pre-v1.0.0 minor-release rule. Prepare
module-selected `cmd/releasekit` with that executable into temporary storage dependencies, then build the module-selected `cmd/releasekit` with that
outside the repository. Use the native executable for publication so its executable into temporary storage outside the repository. Use the native
exit status and diagnostic state are preserved. Its child Go commands must executable for publication so its exit status and diagnostic state are
find the same selected `go` on `PATH`; the old preserved. Its child Go commands must find the same selected `go` on `PATH`;
`CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them. the old `CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them.
2. Keep ordinary candidate preparation: check access to the authoritative 2. Keep ordinary candidate preparation: check access to the authoritative
remote, choose an unused stable version, review compatibility and content, remote, choose an unused stable version, review compatibility and content,
write `docs/releases/<version>.md` with the exact ConfigKit first line and write `docs/releases/<version>.md` with the exact ConfigKit first line and
@@ -151,8 +163,10 @@ profile wiring without duplicating ReleaseKit's generic behavior.
## Stage 6: Exercise the migration without publishing ConfigKit ## Stage 6: Exercise the migration without publishing ConfigKit
1. Build ReleaseKit from the candidate's `go.mod` selection with the same Go 1. Build ReleaseKit from the candidate's `go.mod` selection with the latest
executable declared by that candidate. In disposable Git fixtures, use selected local Go patch for that minimum's series. Use that same executable
for ReleaseKit's validation, without requiring its patch number to equal
the `go.mod` minimum. In disposable Git fixtures, use
ConfigKit's selected profile with only `expected_push_url` changed to a ConfigKit's selected profile with only `expected_push_url` changed to a
temporary bare remote, and provide a matching committed fixture release temporary bare remote, and provide a matching committed fixture release
note. Never push a ConfigKit tag or source commit to its real remote. note. Never push a ConfigKit tag or source commit to its real remote.

37
docs/roadmap/releasekit.md
View File

@@ -56,18 +56,20 @@ adding a runtime API. Review the resulting module changes and license
treatment under the [OSS policy](../policy/oss.md); tooling use alone does not treatment under the [OSS policy](../policy/oss.md); tooling use alone does not
require an attribution entry. require an attribution entry.
At each release preparation, select the newest Go version available in the At each release preparation, select the newest stable Go series available in
development environment and advance ConfigKit's `go.mod` `go` directive to the development environment. Record that series' first stable release in
that version. This deliberately raises ConfigKit's minimum Go version for ConfigKit's `go.mod` `go` directive (for example, `go 1.26.0` when using Go
consumers when the selected version is newer. Use the same selected Go 1.26.8), retaining a higher patch minimum when a dependency or specific
executable to build the pinned ReleaseKit tool and to run ReleaseKit's correctness fix requires it. This directive is the consumer minimum, not the
validation, with native race prerequisites available. ReleaseKit sets release toolchain version. Use the latest locally available patch in the
`GOTOOLCHAIN=local` for its child commands, so ConfigKit's existing selected series to build the pinned ReleaseKit tool and run its validation,
`CONFIGKIT_BASELINE_TOOLCHAIN` environment selection cannot select a provided it meets that minimum and has 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 different validation toolchain. Prepare the tool and dependencies before
offline candidate validation; the `go.mod` change belongs in the committed offline candidate validation; any `go.mod` change belongs in the committed
candidate. Review any minimum-Go increase as a compatibility change and candidate. Review a minimum-Go increase as a compatibility change and explain
explain its consumer impact in the release note. Before v1.0.0, an intentional its consumer impact in the release note. Before v1.0.0, an intentional
increase requires a minor rather than patch release under ConfigKit's increase requires a minor rather than patch release under ConfigKit's
[versioning policy](../policy/release.md#versioning-and-compatibility). [versioning policy](../policy/release.md#versioning-and-compatibility).
@@ -90,9 +92,9 @@ release process adds no ConfigKit public API or runtime use of ReleaseKit.
- Add the minimal profile and declare ReleaseKit v0.2.0 as a tool dependency in - Add the minimal profile and declare ReleaseKit v0.2.0 as a tool dependency in
`go.mod`, updating `go.sum` and reviewing its dependency and license impact. `go.mod`, updating `go.sum` and reviewing its dependency and license impact.
Document how to build the module-selected tool before offline validation. Document how to build the module-selected tool before offline validation.
The release runbook should select the newest Go available in the development The release runbook should record the selected series' minimum in `go.mod`,
environment, advance `go.mod`, and build ReleaseKit with that same Go use its latest locally available patch to build ReleaseKit and validate the
executable. Keep the selected release command small and do not re-create candidate, and keep the selected release command small. Do not re-create
generic Git guards or Go check sequencing in a wrapper. generic Git guards or Go check sequencing in a wrapper.
- Revise the [release policy](../policy/release.md) and - Revise the [release policy](../policy/release.md) and
[maintainer procedure](../release.md) for candidate publication to `main` [maintainer procedure](../release.md) for candidate publication to `main`
@@ -113,9 +115,10 @@ release process adds no ConfigKit public API or runtime use of ReleaseKit.
- Verify the migration without publishing a real ConfigKit version: exercise - Verify the migration without publishing a real ConfigKit version: exercise
the selected profile and release command against an isolated candidate and the selected profile and release command against an isolated candidate and
temporary Git remote, including a validation failure and successful tag temporary Git remote, including a validation failure and successful tag
publication. Confirm that the selected Go executable matches the candidate's publication. Confirm that the candidate's `go.mod` records the selected
`go.mod` directive, builds ReleaseKit, and runs the selected gates once. Do series' minimum or a required higher patch, and that the same selected Go
not make a separate successful CI run a release condition. executable 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 Historical tags and release notes remain unchanged. This adoption work does
not itself authorize publication of a ConfigKit version. not itself authorize publication of a ConfigKit version.