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. A later implementation plan will own 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.

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 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 increase requires a minor rather than patch release under ConfigKit's versioning policy.

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 a documented, versioned tool-preparation method. 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 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, 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 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.

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

Open Decisions

How should ConfigKit pin and acquire ReleaseKit?

Recommendation: Use a separately installed ReleaseKit executable pinned to v0.2.0 for the first migration, built with the Go version selected during release preparation. Document acquisition before offline validation. ConfigKit has no hosted-delivery workflow to coordinate with a CI tool pin, so this keeps ReleaseKit and its tool dependencies out of ConfigKit's library module graph. The OSS policy does not require an attribution entry merely for using a development tool.

Viable alternative: Declare ReleaseKit in ConfigKit's go.mod and use its module-selected tooling convention. This gives local publication and any future tag-triggered delivery one version declaration, but adds tool dependencies to the library's module graph and requires dependency and attribution review.

Should ConfigKit keep its stricter local publication guards?

Recommendation: Adopt ReleaseKit's note-heading rule and exact expected_push_url check, while continuing to write notes as # ConfigKit <version>. Update policy wording to match the actual automated guards. ReleaseKit checks the effective publication endpoint and queries that endpoint for remote state; retaining a second ConfigKit-specific fetch-URL and exact-heading checker would preserve local release machinery for little added value.

Viable alternative: Retain small product checks for ConfigKit's exact first-line title and both configured fetch and push URLs. This preserves the current local policy literally, but makes ConfigKit continue owning and testing release-specific checks alongside ReleaseKit's standard guards.

Must the release command list skipped filesystem tests?

Recommendation: Treat per-test skip output as optional diagnostic detail and revise the runbook's statement that the release checker reports it. ReleaseKit's single standard suite is not verbose, while failed tests still block publication. This avoids an extra test run solely for output.

Viable alternative: Ask ReleaseKit for a supported verbosity selection within its one base test invocation. This preserves the current skip display without duplicating the suite, but expands the shared API and may add output that other consumers do not need.