Plan ReleaseKit v0.9.0 adoption
This commit is contained in:
187
docs/roadmap/releasekit-v0.9.0.md
Normal file
187
docs/roadmap/releasekit-v0.9.0.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# ReleaseKit v0.9.0 adoption
|
||||
|
||||
Status: proposed maintenance roadmap; no implementation has started. Upgrade
|
||||
scope is defined below. The scheduling of existing local corrections remains
|
||||
open under OD-1. This document does not authorize source or hosted publication.
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
Adopt ReleaseKit v0.9.0's improved recovery behavior while preserving
|
||||
CommandKit's existing release-tooling architecture. Update current dependency
|
||||
and maintainer documentation together, and make the validation evidence clear
|
||||
about existing local defects.
|
||||
|
||||
The [agent policy](../policy/agents.md),
|
||||
[release policy](../policy/release.md#candidate-validation),
|
||||
[testing policy](../policy/testing.md#upstream-integration-testing-ownership),
|
||||
and [documentation policy](../policy/documentation.md) govern the work. Current
|
||||
behavior remains owned by the [release procedure](../release.md), Go declarations,
|
||||
and owning package tests until implementation updates them.
|
||||
|
||||
## Current baseline and review evidence
|
||||
|
||||
CommandKit baseline: `98e7e9933353cf43f2be4a96cb0436a0bce068d2`.
|
||||
|
||||
- The root [module](../../go.mod) selects
|
||||
`go.maximumdirect.net/releasekit v0.8.0` as a Go tool. Its selected version
|
||||
serves core, ckconfig, and ckprompt operations.
|
||||
- The [shared helper](../../scripts/releasekit) already normalizes the Go host,
|
||||
disables workspace discovery, selects the local toolchain, retains read-only
|
||||
metadata, and invokes the full executable package path. The
|
||||
[legacy entry point](../../scripts/release) delegates publication to it.
|
||||
- All three profiles already select the agreed generic file checks, forbidden
|
||||
token path, and page-only Gitea destination. Source publication and hosted
|
||||
delivery are separate operations. The local token directory remains ignored.
|
||||
- [R1 and R2](remediation.md) remain open: legacy selector/raw-command collisions
|
||||
and loss of optional POSIX-shell handling in launcher tests.
|
||||
- Both integrations still require older published CommandKit dependencies than
|
||||
their current source needs. The completed [implementation record](implementation.md)
|
||||
distinguishes workspace-backed tests from independent release readiness.
|
||||
|
||||
The upstream v0.9.0 tag identifies commit
|
||||
`2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`. The tag and direct Go-module
|
||||
resolution were verified. The default proxy initially returned v0.8.0 for
|
||||
`@latest`; select v0.9.0 explicitly rather than changing repository-wide proxy
|
||||
settings to work around that observation.
|
||||
|
||||
Upstream [release notes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/releases/v0.9.0.md)
|
||||
describe host-safe launchers and generated recovery commands, full package-path
|
||||
tool selection, preservation of wildcard and version-specific replacements in
|
||||
API-only recovery, and safer manual hosted-page retries. Public Go APIs,
|
||||
profiles, record formats, and the Go 1.26.0 consumer minimum remain unchanged.
|
||||
The v0.8.0-to-v0.9.0 comparison also left upstream module requirements, checksums,
|
||||
copyright, and license texts unchanged.
|
||||
|
||||
A disposable CommandKit upgrade changed only the selected ReleaseKit version in
|
||||
`go.mod`. With Go 1.26.8, the root suite passed on a subsequent run, both
|
||||
workspace-backed integration suites passed, and the real helper reported v0.9.0
|
||||
under foreign target settings. No production publication or delivery was run.
|
||||
|
||||
The initial upgrade run failed in
|
||||
[`TestCompletionCommandContext`](../../completion_context_test.go). The same
|
||||
alias-order failure reproduced four times in 30 focused repetitions on the
|
||||
unchanged v0.8.0 baseline. A single passing rerun therefore does not establish
|
||||
stable validation. The test compares an internal alias slice in a fixed order;
|
||||
commit `0acbbf4` deliberately changed completion to use unsorted lookup records
|
||||
before this upgrade review.
|
||||
|
||||
## Targeted end state
|
||||
|
||||
### Tool adoption and retained architecture
|
||||
|
||||
The root module selects ReleaseKit v0.9.0 with authentic downloaded checksums.
|
||||
Its existing tool declaration and root-owned selection remain. No integration
|
||||
dependency version, library import path, Go minimum, or selected Go 1.26.8
|
||||
maintainer toolchain changes as part of adoption.
|
||||
|
||||
Keep host normalization and full-package invocation in the existing helper:
|
||||
upgrading a dependency does not update or replace local shell scripts. Keep one
|
||||
module/profile mapping and the established wrapper forms. Retain the selected
|
||||
profiles, token-file handling, credential-directory ignore rule, and separation
|
||||
of source and hosted outcomes. No new validator, binary target, CI workflow,
|
||||
publication channel, credential preflight gate, or runtime API is needed.
|
||||
|
||||
The new generated Go recovery commands complement the helper's existing host
|
||||
handling. Recovery continues to use saved publication evidence and the upstream
|
||||
record formats; CommandKit does not acquire a parallel recovery implementation.
|
||||
|
||||
### Current documentation and history
|
||||
|
||||
Current release procedure, project-specific release policy, consumer Go-tool
|
||||
selection summary, and root attribution describe v0.9.0. Upstream contract and
|
||||
notice links use the corresponding immutable source revision. Record that the
|
||||
host-safe launcher request has shipped upstream instead of describing it as
|
||||
pending in the earlier feature roadmap.
|
||||
|
||||
Preserve the baseline and validation history in completed implementation and
|
||||
review records. Do not mechanically replace every historical v0.8.0 reference.
|
||||
Integration attribution describes its own selected published dependency graph;
|
||||
update it only if that actual selection changes. No license-text replacement
|
||||
is needed for the unchanged upstream texts.
|
||||
|
||||
### Local correctness work
|
||||
|
||||
R1 and R2 keep their scope and acceptance evidence in [remediation.md](remediation.md).
|
||||
The dependency upgrade does not close either finding. Subject to OD-1, address
|
||||
them in the same maintenance effort while retaining the simplified test boundary
|
||||
and the legitimate raw helper commands.
|
||||
|
||||
Also correct the completion test's incidental ordering assumption. Compare the
|
||||
expected alias source/target records without depending on their iteration
|
||||
order, while still detecting missing, unexpected, or duplicate records. Sorting
|
||||
test-owned copies is one straightforward approach. Preserve the other routing
|
||||
and visible-completion assertions. Do not restore production sorting or promise
|
||||
a new internal alias order merely to make this assertion pass.
|
||||
|
||||
## Work needed
|
||||
|
||||
- [ ] Record the chosen maintenance scope for OD-1. Keep the upgrade and each local
|
||||
correction reviewable, whether delivered together or separately.
|
||||
- [ ] Select the root tool at v0.9.0, tidy module metadata, and inspect the
|
||||
actual `go.mod`/`go.sum` diff. Investigate unexpected version changes rather
|
||||
than accepting unrelated upgrades. Use normal cache preparation; direct
|
||||
retrieval can diagnose proxy lag without becoming permanent configuration.
|
||||
- [ ] Update current owners: `docs/release.md`, the local selection in
|
||||
`docs/policy/release.md`, `docs/consumers/guide.md`, and the root ReleaseKit
|
||||
entry in `docs/oss/attribution.md`. Check affected source links and fragments
|
||||
at the v0.9.0 commit. Update the earlier feature roadmap's pending-request
|
||||
statement while retaining its historical evidence.
|
||||
- [ ] For bundled correctness work, implement R1 and R2 and the completion
|
||||
assertion repair, with focused verification of the defects. Close existing
|
||||
remediation findings only when their stated behavior has been verified.
|
||||
- [ ] Validate the actual upgraded helper with inherited foreign target values,
|
||||
and run the owning offline suites with Go 1.26.8. During development, use
|
||||
focused repetitions to check the completion repair; do not treat rerunning
|
||||
until green as a substitute for fixing it.
|
||||
- [ ] Exercise selected ReleaseKit checks on the final committed candidate
|
||||
inputs using disposable source snapshots where appropriate. Reuse the
|
||||
completed implementation record's one-time procedure for workspace-backed
|
||||
integration diagnostics; do not add it to ordinary publication or claim it
|
||||
proves independent published-dependency alignment.
|
||||
- [ ] Review whitespace, affected documentation links, and the final diff;
|
||||
record what passed, what remains open, and the reviewed source revision.
|
||||
Commit completed units under the local commit policy.
|
||||
|
||||
No live token, model call, hosted write, or authoritative tag push is needed to
|
||||
verify this maintenance work. Do not read the credential file as part of the
|
||||
upgrade. Ordinary releases still use their single selected-module publication
|
||||
suite, with hosted delivery reported separately. Focused repetitions and
|
||||
disposable-copy diagnostics here are maintenance evidence, not permanent extra
|
||||
release gates.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
Adoption is demonstrated by authentic module metadata, the real helper reporting
|
||||
v0.9.0 for the host, aligned current documentation and attribution, and recorded
|
||||
validation of the final source. The reviewed upgrade introduced no other module
|
||||
version change; verify rather than assume that result during implementation.
|
||||
|
||||
If local corrections are bundled, completion also includes R1/R2 acceptance
|
||||
evidence and a stable, order-independent completion assertion. If delivered
|
||||
separately, report those items as outstanding rather than implying that adoption
|
||||
resolved them. Independent integration dependency alignment remains separate
|
||||
release-preparation work; this roadmap selects no future versions or sums.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Bundle the existing local corrections with the upgrade?
|
||||
|
||||
**Recommendation:** Deliver v0.9.0 adoption, R1, R2, and the completion assertion
|
||||
repair as one focused maintenance effort, using separate reviewable commits as
|
||||
appropriate. The existing issues are small, directly affect maintainer tooling
|
||||
or the default suite, and otherwise leave misleading validation after a passing
|
||||
upgrade run. Fixing the assertion without changing runtime ordering restores
|
||||
useful evidence while keeping the requested contracts intact.
|
||||
|
||||
This is a scheduling recommendation, not a requirement that every dependency
|
||||
upgrade include unrelated repository repairs. It does not fold the older
|
||||
integration dependency-version mismatch into this scope.
|
||||
|
||||
**Viable alternative:** Land the tool and current-documentation updates first,
|
||||
then deliver the three local corrections as separately tracked units. This
|
||||
keeps the dependency change especially easy to review or revert and makes the
|
||||
new recovery behavior available sooner. It leaves the known routing and test
|
||||
issues active, so a passing upgrade run cannot be reported as resolution of
|
||||
those issues or as proof of a consistently passing baseline. Keep their
|
||||
follow-up explicit and apply existing candidate-validation requirements before
|
||||
any actual source publication.
|
||||
Reference in New Issue
Block a user