ConfigKit/docs/roadmap/releasekit.md

Adopt ReleaseKit for source releases

Status: Proposed. This roadmap uses ReleaseKit v0.2.0 (tagged commit e030794969fb7787e647a90bbc4eb81bd0610f07) as the initial adoption baseline. The ReleaseKit release note summarizes its available capabilities. The staged implementation plan owns task order and acceptance checks.

Purpose and current baseline

ConfigKit wants to use a common release process and retire duplicated local release machinery. Today, the release procedure uses scripts/release.sh and scripts/release-check.sh to validate a committed candidate, push it to main, and publish an annotated tag. Dedicated tests exercise those scripts. The selected gates are one offline race-enabled Go suite on a maintained Go 1.25 patch, one full vet pass, and CGO-disabled package builds for Linux amd64 and arm64. The checked-in note and immutable tag are the only declared deliverables. CI and macOS checks do not gate publication; no hosted release page is declared.

ReleaseKit v0.2.0 offers profile selections for that same test, vet, and source-only compilation set. It runs the test suite once, disables test-time vet when a separate full vet pass is selected, and can require an exact effective push URL. Its publication contract requires the candidate to be on authoritative main before validation and pushes only the annotated tag.

Target end state

ConfigKit remains a source-only Go library. Maintainers prepare the version, compatibility assessment, and checked-in note as before, then publish the committed candidate to authoritative main. One ReleaseKit publish invocation validates that exact candidate and publishes its annotated tag. Confirmed publication of the intended tag completes the release. A failed or uncertain push follows ReleaseKit's bounded, exact-object recovery procedure. If validation fails after the candidate is pushed to main, no release tag is published; the corrected candidate requires another commit and validation. No CI wait, consumer installation check, hosted page, or extra human sign-off enters the completion path.

A small releasekit.json profile supplies ConfigKit's product identity, origin, the expected authoritative push URL, and the selected shared Go validation: race, full vet, and package compilation for linux/amd64 and linux/arm64. It declares no executable build or delivery. macOS remains 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.

Declare gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit with a go.mod tool directive and pin its module at v0.2.0, with resolved checksums in go.sum. The release-tool build uses that module selection; there is no separate executable-version pin. This adds release-tool dependencies to ConfigKit's module graph without importing ReleaseKit into library code or adding a runtime API. Review the resulting module changes and license treatment under the OSS policy; tooling use alone does not require an attribution entry.

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; 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.

Use ReleaseKit's note-heading and exact effective-push-URL guards without recreating ConfigKit's current exact-first-line-title or fetch-URL checks. Continue writing release notes with the required # ConfigKit <version> first line, while aligning release policy with the guards that actually run. Per-test skip listings are optional diagnostic output, not a release gate; ReleaseKit's one nonverbose standard suite still blocks publication on test failure.

ReleaseKit owns generic candidate guards, test and compile coordination, tag creation, publication, and push recovery. ConfigKit owns version selection, compatibility review, note content, its selected validation and support targets, and a small integration check of its ReleaseKit configuration. The release process adds no ConfigKit public API or runtime use of ReleaseKit.

Changes from the baseline

• 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 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 and maintainer procedure for candidate publication to main before ReleaseKit's command, its effective-push-URL check, recurring Go version selection and compatibility review, one selected validation pass, tag-only publication, ReleaseKit's standard note and URL guards, optional skip listings, and ReleaseKit's failure states. Preserve ConfigKit's source-only deliverables, supported targets, and no-CI completion rule.
• Update the development guide 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 scripts.
• Retire scripts/release.sh, scripts/release-check.sh, and their duplicated publication and gate tests once ReleaseKit takes over. Preserve the development-check behavior and its tests from release_check_test.go. Retain only a proportionate ConfigKit integration test for the selected profile and invocation where it detects a real wiring error.
• 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 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.