248 lines
14 KiB
Markdown
248 lines
14 KiB
Markdown
# ReleaseKit v0.3.0 upgrade roadmap
|
|
|
|
Status: implemented; ReleaseKit v0.3.0, Go 1.26.0 minimum, and Go 1.26.8
|
|
release toolchain are in place.
|
|
|
|
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 records the target state, completed upgrade work, and evidence
|
|
from the reviewed baseline. 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 | Reviewed 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. | Go 1.26.8, documented separately from the Go 1.26.0 consumer minimum. |
|
|
| 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. The original planning review did not run a test suite or
|
|
publication exercise; completed upgrade validation is recorded below.
|
|
|
|
## 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.
|
|
|
|
## Completed upgrade work
|
|
|
|
### Module and toolchain alignment
|
|
|
|
- [x] Select Go 1.26.8 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
### Validation and completion evidence
|
|
|
|
Use the existing validation boundaries rather than adding recurring release gates:
|
|
|
|
- [x] Run the deterministic offline default suite under the selected toolchain,
|
|
covering the public library and native launcher behavior.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
## Completion evidence
|
|
|
|
Implemented from `efc5065` using Go 1.26.8 on Linux/amd64. The module now
|
|
contains `go 1.26.0`, the retained CLI tool declaration, and the ReleaseKit
|
|
v0.3.0 requirement/checksums. Module tidy retained that selection. No other
|
|
dependency versions changed and no toolchain directive was added. The downloaded
|
|
module's origin identifies the reviewed `e43df4416e0ed987349b2ea04a2c68c25e552772`
|
|
tag revision; dependency preparation required no checksum repair.
|
|
|
|
Validation completed:
|
|
|
|
- Default suite: `go test -mod=readonly -count=1 ./...` passed with `GOWORK=off`,
|
|
`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
|
|
This includes public library and deterministic launcher tests; existing test
|
|
sources were sufficient and unchanged.
|
|
- The existing local publication exercise passed with
|
|
`COMMANDKIT_RELEASE_INTEGRATION=1` and the same offline settings:
|
|
`go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$' -v`.
|
|
It published only within disposable repositories and proved the candidate,
|
|
single suite execution, clean fixture, and endpoint-mismatch behaviors above.
|
|
- A native CLI was built in ignored `.releasekit/bin/` storage with the launcher's
|
|
host-target and readonly settings. Its `version` output was `releasekit v0.3.0`;
|
|
`go version -m` identified Go 1.26.8 and the module-selected v0.3.0 build.
|
|
- `go list -mod=readonly -deps` for the root package and `internal/cobra` found no
|
|
ReleaseKit, Goldmark, or `golang.org/x/mod` runtime imports. The launcher and
|
|
profile were unchanged. ReleaseKit remains tool-only material; no attribution
|
|
entry or copied source was added under the existing OSS policy.
|
|
- The runbook, release policy's local tool selection, consumer compatibility
|
|
explanation, and contributor navigation now describe the upgrade. The
|
|
release policy remains based on v1.6 at its existing upstream revision.
|
|
Local documentation destinations/fragments, shell snippet syntax, and
|
|
whitespace checks passed.
|
|
|
|
This verifies the upgrade without publishing CommandKit or establishing an
|
|
additional recurring release check. No upstream benchmark or test suite was
|
|
rerun; the evidence concerns CommandKit's selected integration.
|
|
|
|
## Release preparation follow-up
|
|
|
|
The next CommandKit release note must explain the Go minimum increase and
|
|
required consumer action. Its CommandKit version is selected during release
|
|
preparation under policy, with the matching note and footer. That separate
|
|
publication task was not performed or authorized by this upgrade; the current
|
|
consumer guide already explains the compatibility change.
|
|
|
|
## Selected decisions
|
|
|
|
### OD-1: release-validation patch version
|
|
|
|
**Resolved: Go 1.26.8, accepted by the user and implemented.** 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 considered: 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.
|