diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0aaa5ab..438264d 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -9,17 +9,18 @@ current release procedure authoritative until the replacement is working. Follow the task-specific reading guide in [development.md](../development.md) and avoid adding gates, compatibility promises, or restrictions beyond the 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 -1. Identify the newest Go executable available in the development environment - when implementing this stage. Make it the `go` on `PATH`, verify it with - `GOTOOLCHAIN=local go version`, and advance ConfigKit's `go.mod` `go` - directive to its full version. Do not substitute a newer downloaded - toolchain during later validation. Record the resulting minimum-Go increase - for the next release's compatibility review; before v1.0.0, an intentional - increase requires a minor release, not a patch release. +1. Identify the latest locally available patch in the newest stable Go series + available in the development environment. Make it the `go` on `PATH` and + verify it with `GOTOOLCHAIN=local go version`. Keep ConfigKit's current + `go.mod` `go` minimum until the release-workflow cutover in Stage 4: the + existing release checker still selects Go 1.25 and cannot validate a module + requiring Go 1.26. Do not substitute an automatically downloaded toolchain + during later validation. 2. Using that same Go executable, add `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0` as a `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 work does not by itself require an attribution entry. -Completion evidence: `go.mod` selects the chosen Go version and the pinned -ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no unintended -changes, the module-selected executable builds with the selected Go, and the -ordinary offline Go suite still passes after dependencies are prepared. +Completion evidence: `go.mod` retains its current Go minimum and selects the +pinned ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no +unintended changes, the module-selected executable builds with the selected +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 @@ -70,8 +74,11 @@ delivery configuration. baseline with the selected local Go executable, the current `go.mod` minimum, the module-selected ReleaseKit CLI, its one race suite with 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 - development environment and reviews any minimum-version increase under + State that preparation records the initial stable release of the newest + 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 before offline candidate validation; do not add a separate successful test or CI run as a publication prerequisite. @@ -89,16 +96,21 @@ stronger automated guards as current behavior. ## Stage 4: Replace the maintainer release runbook 1. Revise [the runbook](../release.md) into copyable steps for the adopted - process. During preparation, select the newest Go executable available in - the development environment, keep it first on `PATH`, verify its version - with `GOTOOLCHAIN=local`, and update `go.mod` to that full version if needed. + process. During this cutover, move `go.mod` from its current minimum to the + first stable release of the newest Go series available in the development + 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 - the pre-v1.0.0 minor-release rule. Prepare dependencies, then build the - module-selected `cmd/releasekit` with that executable into temporary storage - outside the repository. Use the native executable for publication so its - exit status and diagnostic state are preserved. Its child Go commands must - find the same selected `go` on `PATH`; the old - `CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them. + the pre-v1.0.0 minor-release rule. Prepare + dependencies, then build the module-selected `cmd/releasekit` with that + executable into temporary storage outside the repository. Use the native + executable for publication so its exit status and diagnostic state are + preserved. Its child Go commands must find the same selected `go` on `PATH`; + the old `CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them. 2. Keep ordinary candidate preparation: check access to the authoritative remote, choose an unused stable version, review compatibility and content, write `docs/releases/.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 -1. Build ReleaseKit from the candidate's `go.mod` selection with the same Go - executable declared by that candidate. In disposable Git fixtures, use +1. Build ReleaseKit from the candidate's `go.mod` selection with the latest + 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 temporary bare remote, and provide a matching committed fixture release note. Never push a ConfigKit tag or source commit to its real remote. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 98f1b62..7afb70f 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -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 require an attribution entry. -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 +At each release preparation, select the newest stable Go series available in +the development environment. Record that series' first stable release in +ConfigKit's `go.mod` `go` directive (for example, `go 1.26.0` when using Go +1.26.8), retaining a higher patch minimum when a dependency or specific +correctness fix requires it. This directive is the consumer minimum, not the +release toolchain version. Use the latest locally available patch in the +selected series to build the pinned ReleaseKit tool and run its validation, +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 -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 +offline candidate validation; any `go.mod` change belongs in the committed +candidate. Review a 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). @@ -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 `go.mod`, updating `go.sum` and reviewing its dependency and license impact. Document how to build the module-selected tool before offline validation. - 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 + The release runbook should record the selected series' minimum in `go.mod`, + use its latest locally available patch to build ReleaseKit and validate the + candidate, and keep the selected release command small. 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` @@ -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 the selected profile and release command against an isolated candidate and temporary Git remote, including a validation failure and successful tag - 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. + publication. Confirm that the candidate's `go.mod` records the selected + series' minimum or a required higher patch, and that the same selected Go + 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 not itself authorize publication of a ConfigKit version.