# ReleaseKit adoption roadmap Status: adoption complete; RK-01–RK-06 implemented and reviewed. Date: 2026-10-08. ## Purpose and authority This roadmap defines the target state for adopting ReleaseKit as CommandKit's maintainer release tooling and the gaps from its reviewed baseline. The [implementation plan](implementation.md) owns ordered execution steps, stage-specific checks, and implementation evidence. This document does not authorize publication. The completed implementation and its evidence are recorded in the [final adoption audit](implementation.md#stage-6-audit-and-record-adoption-completion). The [release policy](../policy/release.md), [architecture policy](../policy/architecture.md), and [documentation policy](../policy/documentation.md) control the work. Apply the [OSS policy](../policy/oss.md) to dependencies and incorporated material, and the [testing policy](../policy/testing.md) to integration evidence. Existing accepted ADRs continue to govern the library and its standard CLI contracts. The reviewed upstream baseline is ReleaseKit v0.2.0, commit `e030794969fb7787e647a90bbc4eb81bd0610f07`. Its published tag and local checkout matched that revision during adoption review. Upstream references below identify that source; implementation must use the released module rather than require a sibling checkout. ## Current baseline At roadmap preparation, CommandKit is at commit `3871d83` with a clean worktree. Its selected initial library target and documentation reconciliation are complete. The current package inventory is maintained in the [internal overview](../internal/overview.md). | Area | Current state | Adoption gap | | --- | --- | --- | | Module | Go 1.25.5; ConfigKit, PromptKit, and CLI dependencies are declared. | No ReleaseKit tool dependency or version selection. | | Publication | `origin` has effective push URL `https://gitea.maximumdirect.net/eric/CommandKit.git`; no local version tags were present. | No repository publication command or source-only release profile. Remote version availability must be checked when preparing a release. | | Procedure | Release policy is adopted. | `docs/release.md` does not exist; policy still says ReleaseKit integration has not been selected. | | Release history | No `docs/releases/` notes are present. | The first candidate will need its own version-matched note. | | Delivery | No hosted delivery integration is present. | None for the selected source-only adoption target. | | Licensing | Project grant and existing dependency attribution are maintained. | Review the actual tooling and copied-material scope when integration lands. | The adoption review inspected ReleaseKit's implementation and representative tests. It did not execute tests or exercise a CommandKit release integration. This historical baseline is not a claim about later implementation status. ## Target state ### Release ownership and deliverables CommandKit releases remain source-only Go module releases: one immutable version tag identifying an exact committed candidate with its matching checked-in release note. ReleaseKit owns candidate validation, automated publication guards, annotated tag creation, tag publication, and publication outcome reporting. CommandKit maintainers own version selection, candidate contents, compatibility explanations, release-note preparation, dependency preparation, and the repository runbook. The first release version is chosen during release preparation under the release policy; it is not a constant in the publisher or profile. Adoption adds maintainer tooling without adding a production package, a public ReleaseKit wrapper, or a standard application command family. The root `commandkit` facade, internal Cobra boundary, and existing version-reporting responsibilities continue to follow their accepted contracts. ReleaseKit's `buildinfo` package is not needed for this integration. ### Tool selection and launcher CommandKit's root `go.mod` declares `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` as a Go tool dependency, initially selecting ReleaseKit v0.2.0, with committed metadata and checksums. The Go [tool directive](https://go.dev/doc/modules/gomod-ref#tool) retains executable tool dependencies without importing them into the library. The small executable `scripts/release` launcher has publication entry point `./scripts/release VERSION`. It builds the native ReleaseKit CLI selected by the candidate's module configuration, then executes its `publish` command for CommandKit's repository and profile. Bootstrap uses committed module metadata in readonly mode, disabled workspace discovery, and a compatible local toolchain. Its local tool binary lives in ignored `.releasekit/` storage so bootstrap output does not make the candidate dirty. The launcher owns argument handling, repository location, tool bootstrap, and invocation. It preserves the executable's output, exit status, and signal handling. It does not reimplement publication guards, run a separate required `check` first, push `main` automatically, or turn hosted delivery into a publication gate. Build and execute the CLI directly so its distinct failure statuses remain available to maintainers. ReleaseKit's requirements expand the module graph, including its Goldmark and `golang.org/x/mod` dependencies. Review resulting version selections during adoption. Keeping these packages out of library imports avoids runtime linkage; it does not make their module requirements disappear. ### Source-only profile The root `releasekit.json` selects: - product `CommandKit`; - authoritative remote `origin`; and - expected effective push URL `https://gitea.maximumdirect.net/eric/CommandKit.git`. The profile uses the default candidate suite. Additional checks, optional validation selections, binary builds, and hosted delivery are unselected. In particular, the adoption does not establish race, full-vet, cross-platform, formatting, Markdown, module-distribution, or file-size gates. The JSON profile is maintainer configuration for ReleaseKit; it does not change CommandKit's native YAML inspection contracts. Its field definitions remain owned by the upstream [configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/config.md). ### Publication workflow The supported workflow uses a clean committed candidate and matching release note on `main`. Dependency preparation is separate from offline validation. Authoritative remote `main` identifies the candidate before the single launcher publishes its tag. This is the branch-first approach permitted by CommandKit policy; an atomic branch-and-tag publication path is not part of this target. Copyable operational steps belong in the implemented runbook. After publication preflight, ReleaseKit runs one `go test -mod=readonly -count=1 ./...` suite with module and toolchain downloads disabled. It rechecks the candidate and endpoint, creates an annotated tag from the committed note, and pushes only the intended tag object. A successful push completes publication without waiting for CI, module availability, artifacts, or consumer installation. The upstream [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/consumers/publish.md) owns the implementation contract. The runbook must distinguish failures before publication, known unsuccessful pushes, conflicts, and unknown push outcomes. ReleaseKit retains a local tag after a failed push; blindly rerunning the ordinary publisher is not a recovery procedure. Document authoritative remote inspection and the permitted recovery actions under the release policy, preserving published tags and unresolved tag state. Never force an update to bypass a guard. ### Documentation and release notes The target `docs/release.md` owns copyable preparation/publication commands, prerequisites, automated guards, completion point, and recovery instructions. Link to ReleaseKit's owning references for detailed CLI statuses and profile definitions rather than maintaining a second upstream reference in CommandKit's CLI documentation. The procedure explains that ReleaseKit validates the note's product/version heading but does not assess compatibility prose or enforce CommandKit's license footer. Prepare and review that content through ordinary change review. Each release note must include the immutable-tag `COPYRIGHT | LICENSE | ATTRIBUTION` links required by the OSS policy. This introduces no additional network check, manual approval gate, or custom note checker. The implemented release policy identifies the selected integration while preserving substantive rules and provenance. README and developer navigation point to the implemented runbook and describe release-tooling status accurately. Current procedures belong in the runbook; this roadmap owns the target, and the implementation plan owns execution and evidence. ### Licensing and incorporated material Licensing treatment follows the actual selected source, dependency notices, and any incorporated launcher or integration material under the OSS policy. Applicable attribution entries and license texts identify selected upstream revisions and preserve required notices. Tool use alone does not establish an attribution requirement under that policy. Determine treatment from actual incorporation or distribution rather than add entries for every development tool. Any copied or adapted documentation needs its own applicable treatment. CommandKit's runbook is written for this integration, with links to upstream guidance where practical. ## Adoption coverage These IDs identify the target capabilities and remaining baseline gaps. Ordered assignments and checks belong in the implementation plan. | ID | Capability gap | Target result | | --- | --- | --- | | RK-01 | Released Go tool selection | Root module metadata selects v0.2.0 and retains the tool through normal module maintenance; no sibling replacement or library import is needed. | | RK-02 | Source-only profile | Product, authoritative remote, and effective push destination are explicit; only the default suite is selected. | | RK-03 | Publication launcher | One repository publication command builds the module-selected CLI without changing candidate metadata and preserves its outcomes; bootstrap output is ignored. | | RK-04 | Runbook and navigation | Maintainers have one canonical procedure for preparation, publication, and recovery; current documents describe available tooling accurately. | | RK-05 | Licensing treatment | Incorporated material receives policy-conforming attribution and texts without blanket tooling requirements. | | RK-06 | Integration confidence | The launcher/profile work together and adoption respects existing library boundaries; completion evidence and remaining release preparation are recorded in the implementation plan. | ## Acceptance criteria Successful adoption has focused evidence for these integration results: - The repository's committed module configuration selects the tool, including after ordinary module maintenance; bootstrap leaves module files unchanged. - The launcher finds the repository/profile, handles its version argument, preserves ReleaseKit's diagnostic output and distinct exit statuses, and leaves no untracked bootstrap output in candidate status. - A representative disposable repository exercise reaches source publication through the selected launcher/profile without binary or hosted-service work. Use local fixtures, not CommandKit's live remote, for publication evidence. - Invalid candidate or publication preflight state fails through ReleaseKit without bypassing its guards. Focus new coverage on integration mistakes; upstream already owns comprehensive publication and recovery behavior. - The library has no new ReleaseKit runtime imports or exported surface, and affected documentation, notices, paths, and intended release links agree with the implemented integration. The implementation plan selects proportionate checks and reuses existing evidence where sufficient. Adoption checks are not automatically permanent release gates. Diagnostic `check` remains optional; the actual release publisher validates its final candidate once. Adoption is complete when RK-01 through RK-06 are implemented and reviewed, focused evidence is recorded, and the runbook is executable from the documented prerequisites. Publishing CommandKit's first release remains separate work: select a fresh version, prepare its note and final candidate, and follow the runbook with publication authorization. Do not create a placeholder release note or publish a tag merely to complete tooling adoption. ## Adoption completion RK-01 through RK-06 were implemented and reviewed on 2026-10-08. The [implementation plan's final audit](implementation.md#stage-6-audit-and-record-adoption-completion) records validation results and the local commit for each completed stage. No CommandKit release note or tag was created; preparing and publishing the first real release remains separate authorized work under the runbook. ## Deferred capabilities Hosted Gitea release-page delivery is deferred. If selected later, reuse the checked-in release note and report delivery separately from source publication. Use ReleaseKit's [module-selected tooling approach](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/adr/0004-module-selected-tooling.md) so retries select the tool from the released source rather than current `main`. CI integration and credentials become relevant only when that delivery work is selected. Binary targets, assets, build matrices, runtime `buildinfo` integration, and additional validation gates are outside this adoption target. They may be considered later for concrete needs under the owning policies; ReleaseKit's support for them does not establish CommandKit requirements.