Plan release tooling simplification
This commit is contained in:
227
docs/roadmap/release-simplification.md
Normal file
227
docs/roadmap/release-simplification.md
Normal file
@@ -0,0 +1,227 @@
|
|||||||
|
# Release tooling simplification
|
||||||
|
|
||||||
|
Status: proposed implementation roadmap. No implementation has started.
|
||||||
|
The recommendations in Open Decisions remain unselected. This document records
|
||||||
|
the intended simplification and the work to reach it; it does not add release
|
||||||
|
requirements or change public contracts by itself.
|
||||||
|
|
||||||
|
## Purpose and authority
|
||||||
|
|
||||||
|
Reduce CommandKit's release infrastructure to declarative module profiles,
|
||||||
|
a small launcher, and focused tests of CommandKit-owned wiring. Delegate
|
||||||
|
reusable candidate validation and publication mechanics to ReleaseKit while
|
||||||
|
retaining CommandKit's domain-specific checks in their existing owners.
|
||||||
|
|
||||||
|
The [agent policy](../policy/agents.md),
|
||||||
|
[release policy](../policy/release.md#candidate-validation), and
|
||||||
|
[testing policy](../policy/testing.md#upstream-integration-testing-ownership)
|
||||||
|
govern implementation. The [release procedure](../release.md) continues to own
|
||||||
|
the current workflow until implementation updates it.
|
||||||
|
|
||||||
|
## Current baseline
|
||||||
|
|
||||||
|
Baseline: CommandKit commit `a74fcb20041cbccde93f9b9a1e3b24cb8dd131e7`.
|
||||||
|
|
||||||
|
- The root [module](../../go.mod) selects
|
||||||
|
`go.maximumdirect.net/releasekit v0.8.0` as a Go tool. The release toolchain
|
||||||
|
remains Go 1.26.8, and the consumer minimum remains Go 1.26.0.
|
||||||
|
- [Core](../../releasekit.json),
|
||||||
|
[ckconfig](../../integrations/ckconfig/releasekit.json), and
|
||||||
|
[ckprompt](../../integrations/ckprompt/releasekit.json) have separate profiles.
|
||||||
|
They select their physical module directories, the current SSH endpoint, and
|
||||||
|
an explicit repository-root shared-file list. They enable no optional file
|
||||||
|
checks or additional product checks.
|
||||||
|
- The 49-line [launcher](../../scripts/release) maps the three selectors, changes
|
||||||
|
to the repository root, builds the root-selected tool into ignored
|
||||||
|
`.releasekit/bin/` storage for the host, and delegates publication to ReleaseKit.
|
||||||
|
- [Launcher tests](../../scripts/release_test.go) occupy 506 lines, including
|
||||||
|
custom command recording, fake build/publisher processes, and tests of the
|
||||||
|
assertion helpers themselves.
|
||||||
|
- The 399-line [publication exercise](../../scripts/release_integration_test.go)
|
||||||
|
creates disposable Git repositories, release notes, and suite markers. It
|
||||||
|
checks tag structure, exact remote objects, suite counts, nested tag prefixes,
|
||||||
|
and endpoint rejection in addition to exercising CommandKit's launcher.
|
||||||
|
- CommandKit's API, CLI, integration, and maintained consumer behavior is tested
|
||||||
|
in the owning package suites. There is no separate CommandKit-specific
|
||||||
|
candidate-validation implementation to replace or preserve.
|
||||||
|
|
||||||
|
During review, a temporary core profile enabled all four proposed file checks
|
||||||
|
below. ReleaseKit's local `check` accepted the committed core candidate with
|
||||||
|
Go 1.26.8. This was diagnostic evidence only: no profiles changed, no publication
|
||||||
|
occurred, and equivalent integration-module checks remain outstanding.
|
||||||
|
|
||||||
|
## Targeted end state
|
||||||
|
|
||||||
|
### Ownership
|
||||||
|
|
||||||
|
CommandKit retains module selectors, product identities, profile locations,
|
||||||
|
the authoritative endpoint selection, release order, release-note meaning,
|
||||||
|
compatibility decisions, and attribution accuracy. Its existing public API,
|
||||||
|
CLI, integration-adaptation, and consumer-example tests remain local and run
|
||||||
|
through the owning module's suite. No parallel release-only domain suite is
|
||||||
|
needed unless a concrete CommandKit requirement is otherwise unprotected.
|
||||||
|
|
||||||
|
ReleaseKit supplies the standard offline candidate suite, selected generic file
|
||||||
|
checks, candidate/note and publication guards, tag creation and publication,
|
||||||
|
outcome reporting, and recovery. CommandKit's launcher does not repeat those
|
||||||
|
operations. Existing release completion and immutability rules continue to
|
||||||
|
apply; this work adds no publication channel, binary deliverable, or platform
|
||||||
|
support commitment.
|
||||||
|
|
||||||
|
### Profiles
|
||||||
|
|
||||||
|
Subject to OD-1, select these existing ReleaseKit options in each profile:
|
||||||
|
|
||||||
|
| Selection | Intended protection |
|
||||||
|
| --- | --- |
|
||||||
|
| `validation.go_format: true` | Detect unformatted committed Go source. |
|
||||||
|
| `validation.markdown: {}` | Detect broken local Markdown destinations and supported heading fragments. |
|
||||||
|
| `validation.module_distribution.workspace_files: true` | Detect committed development workspace files in selected inputs. |
|
||||||
|
| `validation.module_distribution.local_replacements: true` | Detect filesystem replacements in selected committed module declarations. |
|
||||||
|
|
||||||
|
Retain the explicit shared-file lists and use ReleaseKit's existing input scope.
|
||||||
|
The root profile does not validate every nested module. File checks inspect
|
||||||
|
committed inputs and do not replace formatting worktree changes or reviewing
|
||||||
|
documentation meaning, attribution, and external links. Markdown keeps its
|
||||||
|
default treatment of outside-checkout destinations; no stricter boundary mode
|
||||||
|
is proposed.
|
||||||
|
|
||||||
|
The pinned [ReleaseKit configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md)
|
||||||
|
owns exact scope and behavior, including nested-module boundaries and vendored
|
||||||
|
inputs. Do not expand an option's scope into a general repository prohibition.
|
||||||
|
Race testing, full vet, compilation matrices, size limits, and forbidden-file
|
||||||
|
lists are not selected by this roadmap. They can be considered separately for
|
||||||
|
demonstrated needs.
|
||||||
|
|
||||||
|
### Launcher and recovery
|
||||||
|
|
||||||
|
Subject to OD-2, use the root module's registered `go tool releasekit` through
|
||||||
|
`exec`, keeping the current selector interface and publication argument mapping.
|
||||||
|
Retain host normalization, workspace-off execution, the local toolchain, and
|
||||||
|
read-only module metadata. Preserve other effective Go settings rather than
|
||||||
|
silently replacing them while arranging read-only selection. Go 1.26.8's
|
||||||
|
`go tool` does not accept `-mod=readonly` directly; use its supported Go settings
|
||||||
|
mechanism and verify the intended behavior.
|
||||||
|
|
||||||
|
Remove explicit executable storage and the dedicated ignore entry when the
|
||||||
|
launcher no longer creates that storage. Update recovery instructions to use
|
||||||
|
the registered tool or the entry point printed for the saved attempt. Preserve
|
||||||
|
ReleaseKit's distinction between publication outcome and record-storage errors.
|
||||||
|
|
||||||
|
A pending upstream request concerns host-safe consumer launcher examples and
|
||||||
|
regression coverage. It is not a dependency of this work: v0.8.0 already supports
|
||||||
|
registered tools. Keep host normalization locally because the reviewed
|
||||||
|
`go tool` invocation inherited foreign `GOOS`/`GOARCH` values and failed to run.
|
||||||
|
Do not switch tool-version selection from the root module to each integration
|
||||||
|
merely to match the upstream multi-module example.
|
||||||
|
|
||||||
|
### Focused local tests
|
||||||
|
|
||||||
|
Replace the release-test scaffolding with a small controlled Go-command boundary
|
||||||
|
that invokes the actual launcher. Cover:
|
||||||
|
|
||||||
|
- Selector-to-profile/module routing for core, ckconfig, and ckprompt, including
|
||||||
|
consistency with the checked-in profiles' intended module and product.
|
||||||
|
- Invalid argument handling before tool invocation.
|
||||||
|
- Invocation from another directory and paths containing spaces.
|
||||||
|
- Host normalization and workspace/toolchain/read-only settings.
|
||||||
|
- Publication argument, output-stream, and child exit-status forwarding.
|
||||||
|
|
||||||
|
Exercise module routing separately from exit statuses rather than multiplying
|
||||||
|
every combination. Assert behavior and meaningful selections, not helper
|
||||||
|
implementation details or exact usage prose.
|
||||||
|
|
||||||
|
Remove the disposable publication exercise and its Git fixtures, synthetic
|
||||||
|
notes, markers, tag inspection, and environment-isolation helpers when no longer
|
||||||
|
used. Remove assertion-helper self-tests and the custom build-call log/parser
|
||||||
|
with their obsolete consumers. Trust upstream publication-engine coverage;
|
||||||
|
do not move a duplicate suite into a different local package or export a new
|
||||||
|
test-helper API. There is no line-count target for the replacement tests.
|
||||||
|
|
||||||
|
## Work from baseline to target
|
||||||
|
|
||||||
|
### 1. Select profile checks
|
||||||
|
|
||||||
|
- [ ] Resolve OD-1 and record the chosen scope here.
|
||||||
|
- [ ] Update the three profiles for the selected options while preserving their
|
||||||
|
module identities, endpoint, and shared-file selections.
|
||||||
|
- [ ] Run the selected checks against each module's committed candidate inputs.
|
||||||
|
Review findings against existing contracts; fix relevant defects without
|
||||||
|
introducing broad exclusions or unrelated remediation by default.
|
||||||
|
- [ ] Update the release procedure's selected-check description in the same unit.
|
||||||
|
|
||||||
|
### 2. Simplify the launcher and its tests
|
||||||
|
|
||||||
|
- [ ] Resolve OD-2 and implement the selected invocation path.
|
||||||
|
- [ ] Add or adapt focused wiring tests before deleting the coverage they replace.
|
||||||
|
- [ ] Remove `scripts/release_integration_test.go`, assertion-helper self-tests,
|
||||||
|
and unused build/publisher scaffolding after reviewing their coverage ownership.
|
||||||
|
- [ ] If registered-tool execution is selected, remove executable-storage setup
|
||||||
|
and the dedicated `.releasekit/` ignore entry. Do not delete user-local files
|
||||||
|
as part of the refactor.
|
||||||
|
- [ ] Update recovery commands and remove obsolete opt-in publication-exercise
|
||||||
|
instructions from the release and development guides with the corresponding
|
||||||
|
behavior change.
|
||||||
|
|
||||||
|
### 3. Validate and finish
|
||||||
|
|
||||||
|
- [ ] Validate with Go 1.26.8 and prepared dependencies. Exercise the real
|
||||||
|
registered tool's host execution and read-only behavior once where the local
|
||||||
|
wiring tests use a controlled process; use nonpublishing operations.
|
||||||
|
- [ ] Run the owning module suites and selected ReleaseKit checks against the
|
||||||
|
final candidates. ReleaseKit `check` already runs the selected module's suite;
|
||||||
|
avoid repeating the same successful suite solely for another checklist item.
|
||||||
|
- [ ] Distinguish workspace behavior evidence from each module's independent
|
||||||
|
dependency graph. For disposable committed-candidate checks, use matching
|
||||||
|
notes and existing module metadata; do not invent future dependency versions
|
||||||
|
or checksums to make validation pass.
|
||||||
|
- [ ] Review the documentation, local links, and final diff. Confirm that
|
||||||
|
domain-specific package tests remain and that removed helpers have no users.
|
||||||
|
- [ ] Record validation results and completed work here. Retire the completed
|
||||||
|
roadmap through the usual documentation lifecycle when appropriate.
|
||||||
|
|
||||||
|
These are migration tasks, not additional permanent release gates. Verification
|
||||||
|
needs no production tag push or hosted delivery. Ordinary releases continue to
|
||||||
|
use one publication command, with no required preliminary `check` run.
|
||||||
|
|
||||||
|
## Open Decisions
|
||||||
|
|
||||||
|
### OD-1: Which optional checks become release gates?
|
||||||
|
|
||||||
|
**Recommendation:** Select all four options in the profiles table. Formatting
|
||||||
|
and local link checks automate existing contributor review work. The two module
|
||||||
|
distribution checks address accidental inclusion of development-only metadata
|
||||||
|
that a successful local test run can overlook. Reusing upstream mechanisms keeps
|
||||||
|
this protection declarative and avoids maintaining local checker code.
|
||||||
|
|
||||||
|
This is a deliberate addition to release-time validation, not merely deletion
|
||||||
|
of duplicate code. The observed core pass does not establish every module's
|
||||||
|
compatibility with the selected input scope. Resolve integration findings and
|
||||||
|
the applicability of vendored or fixture inputs before treating the selection
|
||||||
|
as adopted. Record the chosen release scope in the release procedure.
|
||||||
|
|
||||||
|
**Viable alternative:** Select formatting and Markdown now and defer the module
|
||||||
|
distribution checks. This automates familiar review work with less change to
|
||||||
|
accepted release contents, and preserves flexibility for legitimate committed
|
||||||
|
module fixtures. It leaves accidental workspace files or filesystem replacements
|
||||||
|
to ordinary review. Choose this alternative if the broader distribution checks
|
||||||
|
would reject justified inputs or their added protection does not warrant the
|
||||||
|
restriction. Do not compensate by writing equivalent local validators.
|
||||||
|
|
||||||
|
### OD-2: Registered tool or persistent native executable?
|
||||||
|
|
||||||
|
**Recommendation:** Use host-normalized `go tool releasekit`. The tool is already
|
||||||
|
registered in the root module, the Go cache supplies the executable, and the
|
||||||
|
launcher can forward its exit status without managing `.releasekit/bin/`.
|
||||||
|
This also removes storage-specific test machinery and documentation. Preserve
|
||||||
|
read-only metadata selection and test the effective environment before replacing
|
||||||
|
the current bootstrap.
|
||||||
|
|
||||||
|
**Viable alternative:** Retain the current native build and persistent executable
|
||||||
|
while simplifying profiles and tests. It is already proven to handle inherited
|
||||||
|
cross-build targets, accepts an explicit build-time read-only flag, and provides
|
||||||
|
a durable recovery entry point independent of a later Go-driver invocation.
|
||||||
|
It retains storage, bootstrap, and recovery-documentation maintenance, so it
|
||||||
|
removes less local infrastructure. Prefer it only if verification identifies a
|
||||||
|
meaningful recovery or tool-resolution need that the registered-tool path does
|
||||||
|
not meet; the pending upstream example change alone is not such a blocker.
|
||||||
Reference in New Issue
Block a user