diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..0aaa5ab --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,193 @@ +# Implement ReleaseKit adoption + +Status: Planned. Implement the stages below in order. The target state and +policy choices are in the [ReleaseKit adoption roadmap](releasekit.md); this +plan is the execution checklist. Use ReleaseKit v0.2.0 at tagged commit +`e030794969fb7787e647a90bbc4eb81bd0610f07` for the initial migration. +Do not publish a real ConfigKit version as part of implementation. Keep the +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. + +## 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. +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 + requirement). Update `go.sum`, run `go mod tidy`, and inspect the module + diff. Preserve ConfigKit's runtime dependency boundary: production library + packages must not import ReleaseKit. Do not introduce a second tool-version + pin or an `@version` installation path in the release procedure. +3. Prepare the module cache and build the selected CLI package with that Go + executable into a temporary path outside the worktree. Confirm that the + resolved ReleaseKit module is v0.2.0 and that the built executable runs. + Review actual dependency and license treatment under the + [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. + +## Stage 2: Add ConfigKit's ReleaseKit profile + +1. Add `releasekit.json` at the repository root with `product` set to + `ConfigKit`, `remote` set to `origin`, and `expected_push_url` set to + `https://gitea.maximumdirect.net/eric/ConfigKit.git`. Select + `validation.go.race: true`, `validation.go.full_vet: true`, and + `validation.go.compile_targets` in this order: `linux/amd64`, `linux/arm64`. + Omit `build`, `delivery`, `checks`, and the other optional validation + selections. This is a source-only release; macOS is best effort. +2. Add one small, offline ConfigKit-owned test of the committed profile's + selected identity, endpoint, and checks. Keep it limited to configuration + wiring and the agreed gate set; do not replicate ReleaseKit's publication, + recovery, or Go-check implementation tests. Stage 6 will exercise the + profile with the actual tool against an isolated remote. + +Completion evidence: the profile is valid JSON, the focused test and ordinary +Go suite pass, and review shows only the selected gates and no binary or hosted +delivery configuration. + +## Stage 3: Align release policy with the adopted workflow + +1. Revise [the release policy](../policy/release.md) so candidate preparation + explicitly publishes the committed candidate to authoritative `main` + before the one ReleaseKit `publish` invocation validates it and publishes + the annotated tag. Keep the checked-in note and tag as the only deliverables, + successful intended-tag publication as completion, and CI, macOS, hosted + delivery, and consumer retrieval outside release gates. +2. Replace references to the local release scripts and fixed Go 1.25 release + 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 + 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. +3. Align the guard descriptions with ReleaseKit v0.2.0: use its release-note + H1 and exact effective push-URL checks, rather than claiming an automated + exact-first-line or configured fetch-URL check. Retain the required + `# ConfigKit ` first-line format for notes, the source/tag + immutability rules, and the existing recovery principles. Do not require + per-test skip listings; test failures still block publication. + +Completion evidence: policy and roadmap agree on order, gates, compatibility, +and completion; no policy passage still describes the retired script or its +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. + 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. +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 + license footer, retire completed roadmaps, and commit the entire candidate. + Do not turn those reviews into additional approval gates. Push only that + committed candidate to authoritative `main` using the literal authoritative + URL and `HEAD:refs/heads/main` refspec, with implicit tag following + disabled. ReleaseKit requires the remote `main` to equal the candidate + before it validates. A failure before this push leaves publication + unstarted; a failed validation after it leaves an untagged `main` candidate + that must be corrected by a new commit and another validation. +3. Document one `releasekit publish vMAJOR.MINOR.PATCH` invocation using the + built, module-selected executable. Describe its selected race suite, full + vet, Linux package builds, release-note and effective-push-URL guards, + exact tag publication, and confirmed-tag completion. Keep `check` optional + for diagnosis, not a repeated required pass. Update the partial/unknown + push recovery directions to ReleaseKit's reported candidate, endpoint, + tag-object ID, and bounded authoritative-state reconciliation. Preserve + optional post-publication consumer verification and no-CI-wait behavior. + Remove old script commands, Go 1.25 pin examples, and promises of verbose + skipped-test output. + +Completion evidence: a maintainer can follow the runbook from a clean checkout +through confirmed tag publication without a ConfigKit release wrapper or a +second required Go/test run; all commands, version placeholders, and documented +failure states match ReleaseKit v0.2.0. Do not execute its real publication +command in this stage. + +## Stage 5: Retire duplicated machinery and update developer guidance + +1. Remove `scripts/release.sh`, `scripts/release-check.sh`, and + `release_publish_test.go` after Stages 1–4 supply the replacement. Remove + `TestCheckScriptsReleaseGates` and its now-unused helpers from + `release_check_test.go`. Preserve + `TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure` and + `scripts/check.sh`; rename the test file if helpful so its name reflects + its remaining owner. Retain the small Stage 2 profile-wiring test. Do not + transplant the old publication guard/recovery matrix into ConfigKit tests. +2. Update [the development guide](../development.md) to point to the new + release runbook, remove retired-script references and the fixed release + baseline, and adjust its task-to-test map. Keep the everyday development + check and release validation distinct. Review other live references to the + removed scripts and update only those made stale by this migration; + historical release notes remain unchanged. + +Completion evidence: no live release instruction invokes a removed script; +the default suite and `./scripts/check.sh` pass with the selected Go and +prepared dependencies; the retained tests protect development checks and +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 + 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. +2. Push a committed fixture candidate to temporary `main` and run the built + `publish` command with a deliberately failing fixture test. Confirm + validation fails and creates no release tag, while `main` remains at that + candidate. Correct and commit the fixture, push the new candidate to + temporary `main`, and run `publish` again. Confirm one race-enabled standard + suite, one full vet pass, and one CGO-disabled package compile for each + selected Linux target in that successful invocation; confirm the remote + annotated tag identifies the corrected candidate and contains the checked-in + note. Record child Go invocations with a fixture-only forwarding executable + on `PATH`, or use equivalent direct evidence, rather than inferring the + selected command count merely from success. + +Completion evidence: the isolated failure and success paths demonstrate the +selected profile, module-selected tool, command order, gates, and tag-only +publication. No ConfigKit ref is pushed to its real remote. + +## Stage 7: Check endpoint failure and finish the cutover review + +1. In a fresh disposable fixture/version without an existing tag, check that + a wrong effective push URL is rejected before validation or tag + publication. Do not reuse the version already published in Stage 6, which + would make the existing-tag guard obscure the endpoint result. +2. Compare the runbook's recovery directions with ReleaseKit's reported state + for a failed or uncertain tag push. Repair any mismatch in the runbook; + do not duplicate ReleaseKit's recovery machinery in ConfigKit. This is a + bounded migration exercise, not a new per-release gate or a requirement to + wait for CI. +3. Re-run the affected repository checks after any corrections. Review the + final policy, runbook, development guide, and roadmap together for a + coherent process; confirm that only intended files changed and that no + real ConfigKit release or push occurred. + +Completion evidence: the wrong-endpoint fixture fails for the intended reason, +recovery guidance matches ReleaseKit v0.2.0, tests and documentation checks +pass, and the repository is ready for a separately authorized release. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index a6780f0..98f1b62 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -3,8 +3,8 @@ Status: Proposed. This roadmap uses ReleaseKit v0.2.0 (tagged commit `e030794969fb7787e647a90bbc4eb81bd0610f07`) as the initial adoption baseline. The [ReleaseKit release note](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/releases/v0.2.0.md) -summarizes its available capabilities. A later implementation plan will own -task order and acceptance checks. +summarizes its available capabilities. The staged +[implementation plan](implementation.md) owns task order and acceptance checks. ## Purpose and current baseline