ConfigKit/docs/roadmap/implementation.md

Implement ReleaseKit adoption

Status: Planned. Implement the stages below in order. The target state and policy choices are in the ReleaseKit adoption roadmap; 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 and avoid adding gates, compatibility promises, or restrictions beyond the roadmap and adopted policies. Stages 3–5 are one documentation-and-machinery cutover; do not commit or hand off their intermediate state as a release-ready candidate.

Stage 1: Select Go and declare the release tool — Complete

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 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; a tool used only for development and release work does not by itself require an attribution entry.

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 — Complete

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 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 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.
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 <version> 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 into copyable steps for the adopted 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.
2. Keep ordinary candidate preparation: check access to the authoritative remote, choose an unused stable version, review compatibility and content, write docs/releases/<version>.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 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 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.
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.