233 lines
13 KiB
Markdown
233 lines
13 KiB
Markdown
# 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 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 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
|
|
|
|
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.
|
|
|
|
## 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.
|