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

Plan the ReleaseKit and Go upgrade

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 03:55:42 +00:00
parent 7eebe877cf
commit efc50653f1
1 changed files with 205 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/roadmap/releasekit.md Normal file
View File

@@ -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.