From 0690ff68ecb44c044e34121588303ea18dfe80c4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 8 Oct 2026 13:58:59 +0000 Subject: [PATCH] Plan ReleaseKit adoption for source publication --- docs/roadmap/releasekit.md | 238 +++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 docs/roadmap/releasekit.md diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md new file mode 100644 index 0000000..cef9ef5 --- /dev/null +++ b/docs/roadmap/releasekit.md @@ -0,0 +1,238 @@ +# 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.