ConfigKit/docs/roadmap/releasekit.md

Adopt ReleaseKit for source releases

Status: Complete. The ReleaseKit profile, workflow, and isolated fixture verification are in place. 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 pre-adoption baseline

ConfigKit adopted a common release process to replace duplicated local release machinery. Before this migration, the release procedure used scripts/release.sh and scripts/release-check.sh to validate a committed candidate, push it to main, and publish an annotated tag; dedicated tests exercised those scripts. That workflow selected 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 were the only declared deliverables. CI and macOS checks did not gate publication; no hosted release page was 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 the same selected Go executable must remain first on PATH for the tool build and validation. 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.

ReleaseKit v0.2.0 checks the release-note H1 and exact effective push URL; it does not assert the required first-line format or the configured fetch URL. Continue writing notes with the required # ConfigKit <version> first line. Per-test skip listings are optional diagnostic output, not a release gate; ReleaseKit's one 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

• Added the minimal profile and declared ReleaseKit v0.2.0 as a tool dependency in go.mod, with resolved checksums in go.sum. The library has no runtime import of ReleaseKit, and tooling use alone requires no attribution entry.
• Updated the release policy and maintainer procedure for candidate publication to main before ReleaseKit validation, recurring Go version selection and compatibility review, the selected validation set, tag-only publication, ReleaseKit's note and URL guards, and its failure states. Source-only deliverables, supported targets, and the no-CI completion rule remain unchanged.
• Updated the development guide to distinguish everyday development checks from release validation and to document the selected profile test.
• Retired the local release scripts and duplicated publication/gate tests. The development-check test and small profile-wiring test remain; generic ReleaseKit publication behavior is not duplicated in ConfigKit's tests.
• Completed migration verification exercised the selected profile and release command against isolated candidates and a temporary Git remote, including validation failure, successful tag publication, and wrong-endpoint rejection before validation. It confirmed the selected Go minimum and one invocation of each selected gate, without publishing a real ConfigKit version or requiring a separate CI run.

Historical tags and release notes remain unchanged. This adoption work does not itself authorize publication of a ConfigKit version.