base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Plan staged ReleaseKit adoption

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-08 14:18:58 +00:00
parent 0690ff68ec
commit b56d15159d
2 changed files with 471 additions and 926 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1287
docs/roadmap/implementation.md
View File

File diff suppressed because it is too large Load Diff

110
docs/roadmap/releasekit.md
View File

@@ -7,9 +7,10 @@ Date: 2026-10-08.
## Purpose and authority ## Purpose and authority
This roadmap defines the target state for adopting ReleaseKit as CommandKit's 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 maintainer release tooling and the gaps from its reviewed baseline. The
deliverable is a staged implementation plan based on this target. This document [implementation plan](implementation.md) owns ordered execution steps,
does not authorize publication or claim that release tooling already exists. 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), The [release policy](../policy/release.md),
[architecture policy](../policy/architecture.md), and [architecture policy](../policy/architecture.md), and
@@ -66,19 +67,19 @@ responsibilities continue to follow their accepted contracts. ReleaseKit's
### Tool selection and launcher ### Tool selection and launcher
Declare `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` as a Go tool CommandKit's root `go.mod` declares
dependency in CommandKit's root `go.mod`, initially selecting ReleaseKit `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` as a Go tool dependency,
v0.2.0. Commit the resulting module metadata and checksums. The Go initially selecting ReleaseKit v0.2.0, with committed metadata and checksums. The
[tool directive](https://go.dev/doc/modules/gomod-ref#tool) retains executable Go [tool directive](https://go.dev/doc/modules/gomod-ref#tool) retains executable
tool dependencies without importing them into the library. tool dependencies without importing them into the library.
Provide a small executable `scripts/release` launcher whose publication entry The small executable `scripts/release` launcher has publication entry point
point is `./scripts/release VERSION`. It builds the ReleaseKit CLI selected by `./scripts/release VERSION`. It builds the native ReleaseKit CLI selected by
the candidate's module configuration, then executes its `publish` command for the candidate's module configuration, then executes its `publish` command for
CommandKit's repository and profile. Build the tool with committed module CommandKit's repository and profile. Bootstrap uses committed module metadata
metadata in readonly mode, with workspace discovery disabled and the compatible in readonly mode, disabled workspace discovery, and a compatible local toolchain.
local toolchain selected. Use an ignored `.releasekit/` directory for the local Its local tool binary lives in ignored `.releasekit/` storage so bootstrap output
tool binary so bootstrap output does not make the candidate dirty. does not make the candidate dirty.
The launcher owns argument handling, repository location, tool bootstrap, and The launcher owns argument handling, repository location, tool bootstrap, and
invocation. It preserves the executable's output, exit status, and signal invocation. It preserves the executable's output, exit status, and signal
@@ -94,15 +95,15 @@ it does not make their module requirements disappear.
### Source-only profile ### Source-only profile
Add a root `releasekit.json` selecting: The root `releasekit.json` selects:
- product `CommandKit`; - product `CommandKit`;
- authoritative remote `origin`; and - authoritative remote `origin`; and
- expected effective push URL - expected effective push URL
`https://gitea.maximumdirect.net/eric/CommandKit.git`. `https://gitea.maximumdirect.net/eric/CommandKit.git`.
Use the default candidate suite. Initially leave additional checks, optional The profile uses the default candidate suite. Additional checks, optional
validation selections, binary builds, and hosted delivery unselected. In validation selections, binary builds, and hosted delivery are unselected. In
particular, the adoption does not establish race, full-vet, cross-platform, particular, the adoption does not establish race, full-vet, cross-platform,
formatting, Markdown, module-distribution, or file-size gates. formatting, Markdown, module-distribution, or file-size gates.
@@ -113,17 +114,12 @@ owned by the upstream
### Publication workflow ### Publication workflow
The runbook selects ReleaseKit's supported sequence: The supported workflow uses a clean committed candidate and matching release
note on `main`. Dependency preparation is separate from offline validation.
1. Prepare and commit the candidate and matching release note on `main`. Authoritative remote `main` identifies the candidate before the single launcher
2. Prepare the module dependencies and tool dependencies needed by the local publishes its tag. This is the branch-first approach permitted by CommandKit
compatible toolchain, separately from offline candidate validation. policy; an atomic branch-and-tag publication path is not part of this target.
3. Push the candidate commit to authoritative remote `main` using explicit refs. Copyable operational steps belong in the implemented runbook.
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 After publication preflight, ReleaseKit runs one
`go test -mod=readonly -count=1 ./...` suite with module and toolchain downloads `go test -mod=readonly -count=1 ./...` suite with module and toolchain downloads
@@ -143,8 +139,8 @@ state. Never force an update to bypass a guard.
### Documentation and release notes ### Documentation and release notes
Create `docs/release.md` when the launcher and profile exist. It owns the The target `docs/release.md` owns copyable preparation/publication commands,
copyable preparation/publication commands, prerequisites, automated guards, prerequisites, automated guards,
completion point, and recovery instructions. Link to ReleaseKit's owning completion point, and recovery instructions. Link to ReleaseKit's owning
references for detailed CLI statuses and profile definitions rather than references for detailed CLI statuses and profile definitions rather than
maintaining a second upstream reference in CommandKit's CLI documentation. maintaining a second upstream reference in CommandKit's CLI documentation.
@@ -156,44 +152,42 @@ release note must include the immutable-tag `COPYRIGHT | LICENSE | ATTRIBUTION`
links required by the OSS policy. This introduces no additional network check, links required by the OSS policy. This introduces no additional network check,
manual approval gate, or custom note checker. manual approval gate, or custom note checker.
Update the release policy's undecided-adoption statement when integration lands, The implemented release policy identifies the selected integration while
preserving its substantive rules and provenance. Update README and developer preserving substantive rules and provenance. README and developer navigation
navigation to point to the implemented runbook and remove their obsolete point to the implemented runbook and describe release-tooling status accurately.
release-tooling status statements. Current procedures belong in the runbook; Current procedures belong in the runbook; this roadmap owns the target, and the
this roadmap and the forthcoming staged plan retain target/status information. implementation plan owns execution and evidence.
### Licensing and incorporated material ### Licensing and incorporated material
Review the selected ReleaseKit source, dependency notices, and any copied Licensing treatment follows the actual selected source, dependency notices,
launcher or integration material under the OSS policy. Update applicable and any incorporated launcher or integration material under the OSS policy.
attribution entries and license texts together with incorporation, identifying Applicable attribution entries and license texts identify selected upstream
selected upstream revisions and preserving required notices. revisions and preserve required notices.
Tool use alone does not establish an attribution requirement under that policy. Tool use alone does not establish an attribution requirement under that policy.
Determine treatment from actual incorporation or distribution rather than add Determine treatment from actual incorporation or distribution rather than add
entries for every development tool. Any copied or adapted documentation needs entries for every development tool. Any copied or adapted documentation needs
its own applicable treatment. Author the CommandKit runbook for this integration its own applicable treatment. CommandKit's runbook is written for this
and reuse upstream guidance through links where practical. integration, with links to upstream guidance where practical.
## Work needed from the baseline ## Adoption coverage
These are implementation work areas, not the staged execution instructions. These IDs identify the target capabilities and remaining baseline gaps.
The next plan must order them, specify concrete edits and proportionate evidence, Ordered assignments and checks belong in the implementation plan.
and preserve any changes made after this baseline.
| ID | Work | Completion result | | ID | Capability gap | Target 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-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 | Add the source-only profile. | Product, authoritative remote, and effective push destination are explicit; only the default suite is selected. | | RK-02 | 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-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 | 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-04 | Runbook and navigation | 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-05 | Licensing treatment | 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. | | 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. |
## Completion evidence and handoff ## Acceptance criteria
Select evidence for the new integration rather than duplicate ReleaseKit's entire Successful adoption has focused evidence for these integration results:
candidate and Git test inventory. During implementation, establish that:
- The repository's committed module configuration selects the tool, including - The repository's committed module configuration selects the tool, including
after ordinary module maintenance; bootstrap leaves module files unchanged. after ordinary module maintenance; bootstrap leaves module files unchanged.
@@ -210,10 +204,10 @@ candidate and Git test inventory. During implementation, establish that:
affected documentation, notices, paths, and intended release links agree with affected documentation, notices, paths, and intended release links agree with
the implemented integration. the implemented integration.
The staged plan should identify the checks appropriate to these risks and reuse The implementation plan selects proportionate checks and reuses existing
existing evidence where sufficient. Adoption checks are not automatically evidence where sufficient. Adoption checks are not automatically permanent
permanent release gates. Diagnostic `check` remains optional; the actual release release gates. Diagnostic `check` remains optional; the actual release publisher
publisher validates its final candidate once. validates its final candidate once.
Adoption is complete when RK-01 through RK-06 are implemented and reviewed, 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 focused evidence is recorded, and the runbook is executable from the documented