commandkit/docs/roadmap/releasekit.md

# ReleaseKit adoption roadmap

Status: adoption selected; implementation not started.

Date: 2026-10-08.

## Purpose and authority

This roadmap defines the target state for adopting ReleaseKit as CommandKit's
maintainer release tooling and the work needed to reach it. The next planning
deliverable is a staged implementation plan based on this target. This document
does not authorize publication or claim that release tooling already exists.

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

Declare `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` as a Go tool
dependency in CommandKit's root `go.mod`, initially selecting ReleaseKit
v0.2.0. Commit the resulting module 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.

Provide a small executable `scripts/release` launcher whose publication entry
point is `./scripts/release VERSION`. It builds the ReleaseKit CLI selected by
the candidate's module configuration, then executes its `publish` command for
CommandKit's repository and profile. Build the tool with committed module
metadata in readonly mode, with workspace discovery disabled and the compatible
local toolchain selected. Use an ignored `.releasekit/` directory for the local
tool binary 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

Add a root `releasekit.json` selecting:

- product `CommandKit`;
- authoritative remote `origin`; and
- expected effective push URL
  `https://gitea.maximumdirect.net/eric/CommandKit.git`.

Use the default candidate suite. Initially leave additional checks, optional
validation selections, binary builds, and hosted delivery 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 runbook selects ReleaseKit's supported sequence:

1. Prepare and commit the candidate and matching release note on `main`.
2. Prepare the module dependencies and tool dependencies needed by the local
   compatible toolchain, separately from offline candidate validation.
3. Push the candidate commit to authoritative remote `main` using explicit refs.
4. Invoke the single publication launcher for the selected version.

ReleaseKit requires remote `main` to identify the candidate before publication;
this adoption uses the branch-first approach permitted by CommandKit policy.
An atomic branch-and-tag publication path is not part of this target.

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

Create `docs/release.md` when the launcher and profile exist. It owns the
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.

Update the release policy's undecided-adoption statement when integration lands,
preserving its substantive rules and provenance. Update README and developer
navigation to point to the implemented runbook and remove their obsolete
release-tooling status statements. Current procedures belong in the runbook;
this roadmap and the forthcoming staged plan retain target/status information.

### Licensing and incorporated material

Review the selected ReleaseKit source, dependency notices, and any copied
launcher or integration material under the OSS policy. Update applicable
attribution entries and license texts together with incorporation, identifying
selected upstream revisions and preserving 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. Author the CommandKit runbook for this integration
and reuse upstream guidance through links where practical.

## Work needed from the baseline

These are implementation work areas, not the staged execution instructions.
The next plan must order them, specify concrete edits and proportionate evidence,
and preserve any changes made after this baseline.

| ID | Work | Completion result |
| --- | --- | --- |
| RK-01 | Add the released Go tool dependency and review module resolution. | 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 | Add the source-only profile. | Product, authoritative remote, and effective push destination are explicit; only the default suite is selected. |
| RK-03 | Add the executable launcher and ignore its local build output. | One repository publication command builds the module-selected CLI without changing candidate metadata and preserves its outcomes. |
| RK-04 | Write the implemented release runbook and reconcile navigation/policy status. | Maintainers have one canonical procedure for preparation, publication, and recovery; current documents describe available tooling accurately. |
| RK-05 | Review licensing scope and maintain affected notices. | Incorporated material receives policy-conforming attribution and texts without blanket tooling requirements. |
| RK-06 | Establish focused integration evidence and record completion. | The launcher/profile work together and the adoption respects existing library boundaries; the roadmap records actual completion and remaining release preparation. |

## Completion evidence and handoff

Select evidence for the new integration rather than duplicate ReleaseKit's entire
candidate and Git test inventory. During implementation, establish that:

- 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 staged plan should identify the checks appropriate to these risks and reuse
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.

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