base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 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
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.
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
@@ -66,19 +67,19 @@ responsibilities continue to follow their accepted contracts. ReleaseKit's
### 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
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.
Provide a small executable `scripts/release` launcher whose publication entry
point is `./scripts/release VERSION`. It builds the ReleaseKit CLI selected by
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. 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.
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
@@ -94,15 +95,15 @@ it does not make their module requirements disappear.
### Source-only profile
Add a root `releasekit.json` selecting:
The root `releasekit.json` selects:
- 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
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.
@@ -113,17 +114,12 @@ owned by the upstream
### 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.
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
@@ -143,8 +139,8 @@ 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,
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.
@@ -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,
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.
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
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.
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. Author the CommandKit runbook for this integration
and reuse upstream guidance through links where practical.
its own applicable treatment. CommandKit's runbook is written for this
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.
The next plan must order them, specify concrete edits and proportionate evidence,
and preserve any changes made after this baseline.
These IDs identify the target capabilities and remaining baseline gaps.
Ordered assignments and checks belong in the implementation plan.
| 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-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. |
| 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. |
## Completion evidence and handoff
## Acceptance criteria
Select evidence for the new integration rather than duplicate ReleaseKit's entire
candidate and Git test inventory. During implementation, establish that:
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.
@@ -210,10 +204,10 @@ candidate and Git test inventory. During implementation, establish that:
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.
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