diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md new file mode 100644 index 0000000..89f35a4 --- /dev/null +++ b/docs/roadmap/releasekit.md @@ -0,0 +1,205 @@ +# ReleaseKit v0.3.0 upgrade roadmap + +Status: upgrade and Go 1.26.0 consumer minimum accepted; implementation not begun. + +Date: 2026-10-08. + +## Purpose and authority + +Upgrade CommandKit's maintainer publication tool from ReleaseKit v0.2.0 to +v0.3.0 and simultaneously raise CommandKit's declared Go consumer minimum to +1.26.0. The user has accepted both changes. Retain the existing root-module Go +tool dependency and source-only publication workflow. + +This document defines the desired end state and work needed from the reviewed +baseline. A later implementation plan can define ordered execution steps. The +[release policy](../policy/release.md), +[architecture policy](../policy/architecture.md), +[agent policy](../policy/agents.md), +[testing policy](../policy/testing.md), and +[documentation policy](../policy/documentation.md) govern the work. Apply the +[OSS policy](../policy/oss.md) to any changed attribution or incorporated material. +The [maintainer procedure](../release.md) owns current release operations. + +This is a new upgrade roadmap. The completed initial ReleaseKit adoption is +available in Git history; its retired assignments are not part of this work. +Implementation completion is distinct from publishing a CommandKit release. + +## Reviewed baseline + +CommandKit was reviewed at `7eebe877cf9a21fb4f886f89bbc2089661237fc1` with a clean +worktree. ReleaseKit v0.3.0 identifies commit +`e43df4416e0ed987349b2ea04a2c68c25e552772`; the local checkout and published tag +matched that revision during review. Its [release notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/releases/v0.3.0.md) +record the compatibility and upgrade guidance. + +| Area | Current baseline | Target | +| --- | --- | --- | +| Module | `go 1.25.5`; ReleaseKit v0.2.0 selected through a `tool` directive and module requirement. | `go 1.26.0`; the same CLI tool dependency selects ReleaseKit v0.3.0. | +| Release toolchain | Go 1.25.5 selected in the runbook. The review environment has Go 1.26.8. | One selected Go 1.26 patch toolchain, documented separately from the consumer minimum; see OD-1. | +| Launcher | `scripts/release` builds the module-selected native CLI in readonly mode and delegates publication with argument, status, and stream preservation. | The same bootstrap and delegation use v0.3.0 under the selected compatible toolchain. | +| Profile | `releasekit.json` specifies product, remote, and expected push endpoint; validation uses the default suite. | The same minimal source-only profile. | +| Evidence | Deterministic launcher tests and an opt-in publication exercise against disposable local Git repositories exist. | Those boundaries work with the upgraded module selection and toolchain. | +| Documentation | Policy, runbook, and consumer guide describe v0.2.0 and/or the Go 1.25.5 selection. | Canonical owners describe the implemented upgrade and its consumer impact. | + +The upstream CLI, profile schema, and public signatures are unchanged. ReleaseKit +itself raises its minimum from Go 1.25.0 to 1.26.0; its dependency versions are +unchanged from v0.2.0. No test suite or publication exercise was run during this +planning pass. + +## Target end state + +### Module selection and Go compatibility + +The root [go.mod](../../go.mod) declares **Go 1.26.0** and selects +**ReleaseKit v0.3.0** for `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit`. +The corresponding [go.sum](../../go.sum) records the resolved checksums. The +existing tool declaration retains the executable through ordinary module tidy. + +The tool shares CommandKit's module graph, so the new minimum applies to library +consumers as well as maintainers even though production packages do not import +ReleaseKit. This is an intentional compatibility change. Go 1.25 consumers need +to upgrade before adopting the CommandKit revision containing it. + +The consumer minimum remains the initial stable release of the Go 1.26 series. +A newer release-validation patch does not raise that floor by itself. The +[release policy's toolchain rules](../policy/release.md#consumer-minimum-and-release-toolchain) +define the support presumption and compatibility treatment. No additional +minimum-version test matrix or promise of identical results across toolchains +is introduced. + +### Ownership and publication behavior + +ReleaseKit remains maintainer tooling. The root `commandkit` facade and internal +Cobra adapter keep their existing responsibilities; this upgrade adds no runtime +ReleaseKit import, public wrapper, or operator-facing command family. + +The existing launcher remains the publication entry point. It builds the native +CLI from the committed module selection with readonly metadata and automatic +workspace/toolchain switching disabled. The maintainer's selected `go` on `PATH` +is used for bootstrap and candidate validation. A `toolchain` directive is not +needed to make this launcher select that executable; setup belongs in the runbook. + +CommandKit continues to publish an annotated source tag after its candidate is +available on the authoritative branch. ReleaseKit owns validation, publication +guards, tag creation, and publication outcome reporting. CommandKit owns the +candidate, version, note, profile, and runbook. Successful publication remains +separate from optional delivery investigations under the existing release policy. + +### Benefits within the selected scope + +ReleaseKit v0.3.0 reduces output-copying and retention during Go command +execution, preserving full failure diagnostics and underlying causes. That +improvement benefits CommandKit's default candidate suite. + +The upstream Git reader, file-check caches, cancellation cleanup, asset hashing, +and runtime-version improvements remain upstream responsibilities. Our current +profile does not enable optional committed-file checks or hosted artifact +delivery. Their improvements are available if those capabilities are deliberately +selected later; this upgrade does not enable them. No CommandKit latency or +allocation target is part of adoption. + +## Work needed + +### Module and toolchain alignment + +- Select the release-validation patch under OD-1 and document its installation + and `PATH` setup in the runbook. Use that toolchain for upgrade validation and + subsequent release tasks governed by the procedure. +- Upgrade the existing CLI tool dependency to v0.3.0 and set the Go directive to + exactly 1.26.0 using ordinary Go module tooling. Review the resulting module + and checksum changes, including any automatically generated toolchain metadata. + Keep the consumer floor separate from the maintainer patch selection. +- Prepare dependencies before offline validation. The local sibling checkout is + review evidence, not a replacement module or build prerequisite. Diagnose any + checksum failure using upstream guidance and retain checksum verification. +- Review incidental module changes. ConfigKit, PromptKit, and backend upgrades + are separate work; v0.3.0 does not require new versions of its own dependencies. + +### Launcher and profile verification + +- Confirm the existing launcher builds the upgraded native executable from the + module-selected package and preserves publication arguments, streams, and + statuses. Confirm that the executable identifies ReleaseKit v0.3.0. +- Retain the current profile and launcher design. Change implementation only if + a demonstrated compatibility issue requires it; no migration is indicated by + the reviewed upstream CLI or schema. +- Reuse existing launcher tests. Adjust fixtures only where the selected version + or Go requirement actually affects their behavior. An older version string + used to test rejection of an independent package pin need not be replaced just + because the adopted version changes. + +### Canonical documentation and provenance + +- Update [docs/policy/release.md](../policy/release.md) to identify the selected + ReleaseKit version while retaining its v1.6 upstream provenance and local + source-only rules. This tooling upgrade is not another policy-template adoption. +- Update [docs/release.md](../release.md) with the selected Go 1.26 patch, + executable setup commands, and v0.3.0 source-pinned upstream references. Keep + versioning rules in the policy and operations in the runbook. +- Update the [consumer guide](../consumers/guide.md#go-compatibility) to explain + the Go 1.26.0 minimum and shared tool-module reason. The current attribution + of the floor to PromptKit's Go 1.25.5 requirement becomes obsolete. +- Check contributor navigation and current references affected by the upgrade. + Historical planning records and immutable release notes retain their original + facts; avoid replacing every historical version string. +- Apply the [OSS policy](../policy/oss.md) to the actual material scope. Tool use + alone does not require a new attribution entry. Update entries or license links + if incorporated material or dependency selection changes require it. +- Explain the Go minimum increase and required consumer action in the next + CommandKit release note. Select the CommandKit version during release + preparation under policy, rather than borrowing ReleaseKit's version or + creating an arbitrarily named release note during this upgrade. + +### Validation and completion evidence + +Use the existing validation boundaries rather than adding recurring release gates: + +- Run the deterministic offline default suite under the selected toolchain, + covering the public library and native launcher behavior. +- Exercise the existing opt-in local publication test with the upgraded module + selection after cache preparation. It covers a real native bootstrap, exact + candidate tag publication to a disposable bare repository, one candidate suite, + clean fixture state, and endpoint-mismatch preflight. Keep it opt-in in normal + development and publication; this is upgrade evidence, not a new release gate. +- Inspect production package dependencies to confirm ReleaseKit remains outside + the root library and internal adapter import closures. Review module selection + and CLI version evidence separately from that runtime boundary. +- Review canonical-document changes, local links/fragments, provenance, and + whitespace. Record the actual toolchain, resolved module revision, checks run, + outcomes, and any qualifications when marking this roadmap implemented. + +The [developer guide](../development.md#release-tooling-development) owns the +existing local exercise commands. Reuse successful evidence for unchanged +content; adding a benchmark requirement, platform matrix, or upstream suite +rerun is not necessary to establish this upgrade's selected behavior. + +## Completion criteria + +The upgrade is implemented when the root module selects v0.3.0 with Go 1.26.0, +the documented release toolchain can bootstrap and validate it, existing +launcher/publication behavior has the stated evidence, and current documentation +accurately describes the minimum and ownership boundaries. Release notes carry +the compatibility explanation when a release containing the change is prepared. + +This work does not publish CommandKit, add hosted delivery, split tooling into a +second module, or change standard CLI/API semantics. Actual publication and its +fresh version-matched note remain a separate release-preparation task. + +## Open Decisions + +### OD-1: release-validation patch version + +**Recommendation: select Go 1.26.8.** It is the toolchain available in the +review environment and used by ReleaseKit v0.3.0's maintainers. Using it avoids +an additional installation in that environment and benefits from later patch +updates within the selected Go series. Declare `go 1.26.0` for consumers and +document 1.26.8 as the runbook's release-toolchain selection. The adopted +policy permits same-series support to be presumed from this validation; a +second mandatory run on 1.26.0 is unnecessary absent a concrete concern. + +**Alternative: select Go 1.26.0.** It validates directly at the consumer floor +and makes the minimum and release toolchain identical initially. It requires +installing that patch in the reviewed environment and forgoes subsequent patch +updates. It is viable if direct minimum-toolchain validation is preferred, but +the current policy does not require that extra alignment.