206 lines
12 KiB
Markdown
206 lines
12 KiB
Markdown
# 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.
|