Finalize release tooling implementation plan
This commit is contained in:
@@ -1,10 +1,11 @@
|
||||
# Release tooling simplification
|
||||
|
||||
Status: implementation roadmap; no implementation has started. Local page-only
|
||||
Gitea delivery and protection of the supplied token path are selected for
|
||||
implementation. The recommendations in Open Decisions remain unselected.
|
||||
Current release behavior stays with its canonical owners until implementation
|
||||
updates them.
|
||||
Status: target design finalized for the release-tooling sprint; implementation
|
||||
has not started. All four generic file checks, registered-tool execution,
|
||||
page-only hosted delivery, and protection of the supplied token path are selected.
|
||||
The [implementation plan](implementation.md) owns stage order, tasks, validation,
|
||||
and completion evidence. Current release behavior stays with its canonical owners
|
||||
until implementation updates them.
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
@@ -21,44 +22,6 @@ The [agent policy](../policy/agents.md),
|
||||
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, and configure no hosted delivery.
|
||||
- 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.
|
||||
|
||||
After the baseline review, the maintainer supplied the local credential file
|
||||
`.releasekit/gitea-token`. Its contents were not read. The file was confirmed
|
||||
ignored, untracked, and mode `0600`; authentication was not tested. The existing
|
||||
directory ignore rule now serves credential storage as well as executable
|
||||
storage and remains needed after executable-storage removal.
|
||||
|
||||
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
|
||||
@@ -79,7 +42,7 @@ deliverables and platform support commitments remain unchanged.
|
||||
|
||||
### Profiles
|
||||
|
||||
Subject to OD-1, select these existing ReleaseKit options in each profile:
|
||||
Select these existing ReleaseKit options in each profile:
|
||||
|
||||
| Selection | Intended protection |
|
||||
| --- | --- |
|
||||
@@ -88,7 +51,7 @@ Subject to OD-1, select these existing ReleaseKit options in each profile:
|
||||
| `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. |
|
||||
|
||||
Separately from OD-1, select
|
||||
Also select
|
||||
`validation.forbidden_files: [".releasekit/gitea-token"]` in all three profiles.
|
||||
This delegates protection of the supplied credential path to ReleaseKit's
|
||||
existing check. The path is repository-relative and the check applies across
|
||||
@@ -111,27 +74,25 @@ 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.
|
||||
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.
|
||||
read-only module metadata. Preserve other effective Go settings while arranging
|
||||
read-only selection.
|
||||
The implementation plan specifies the wrapper interface and invocation details.
|
||||
|
||||
Remove explicit executable storage when the launcher no longer creates it.
|
||||
Retain `/.releasekit/` in `.gitignore` for the credential file, and update its
|
||||
comment to describe that purpose. 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.
|
||||
Go's cache supplies executable storage; the launcher creates no persistent
|
||||
binary directory. `/.releasekit/` remains ignored for the credential file, with
|
||||
an explanatory comment. Recovery instructions use the registered tool or the
|
||||
entry point printed for the saved attempt, preserving ReleaseKit's distinction
|
||||
between publication outcome and record-storage errors.
|
||||
|
||||
Share module selection and host-safe tool invocation between publication,
|
||||
delivery, and recovery where applicable. Delivery selects the same module
|
||||
profile as publication; recovery uses its recorded attempt rather than inferring
|
||||
identity from a current profile. Keep the existing publication interface and
|
||||
provide an explicit delivery invocation without automatically chaining the two
|
||||
operations. Choose a small wrapper arrangement during implementation rather
|
||||
than adding a coordination framework or duplicating selector tables.
|
||||
operations. Keep one selector mapping and shared invocation plumbing.
|
||||
|
||||
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
|
||||
@@ -204,115 +165,34 @@ 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 and delivery 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.
|
||||
The resulting local suite omits the disposable publication exercise, generic
|
||||
tag inspection, assertion-helper self-tests, and custom build-call log/parser.
|
||||
Upstream publication and delivery coverage owns those generic behaviors. No
|
||||
replacement publication engine or exported test-helper API is needed. There is
|
||||
no line-count target for the replacement tests.
|
||||
|
||||
## Work from baseline to target
|
||||
## Selected choices and rationale
|
||||
|
||||
### 1. Configure validation and hosted delivery
|
||||
All four generic file checks are selected as release-time checks, in addition
|
||||
to the agreed forbidden token path. Formatting and local-link validation automate
|
||||
existing contributor review work. Workspace-file and filesystem-replacement
|
||||
checks address accidental inclusion of development metadata that a successful
|
||||
local test run can overlook. This adds specific release checks; it does not
|
||||
make every optional ReleaseKit validator mandatory or prohibit development
|
||||
workspaces and replacements outside the selected committed candidate inputs.
|
||||
Selecting only formatting and Markdown would change less release behavior, but
|
||||
would leave these distribution mistakes to manual review. The selected upstream
|
||||
checks avoid a second local implementation.
|
||||
|
||||
- [ ] 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.
|
||||
- [ ] Add the agreed delivery destination and forbidden token path to each
|
||||
profile. Preserve the ignored token file and the directory ignore rule.
|
||||
- [ ] 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 policy's delivery scope and the release procedure's
|
||||
selected-check and hosted-delivery descriptions with the profile changes.
|
||||
Host-normalized registered-tool execution is selected because the root module
|
||||
already registers ReleaseKit and Go caches the executable. Retaining a persistent
|
||||
native executable would provide a recovery entry point independent of a later
|
||||
Go-driver invocation, but would retain executable-storage and bootstrap test
|
||||
maintenance. Recovery instead uses the registered tool or ReleaseKit's reported
|
||||
entry point. The credential directory remains ignored under either approach.
|
||||
|
||||
### 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
|
||||
while retaining `/.releasekit/` for credentials and updating its comment.
|
||||
Do not delete user-local files as part of the refactor.
|
||||
- [ ] Expose explicit module-aware delivery using shared invocation plumbing.
|
||||
Keep publication and delivery independently invocable and retryable.
|
||||
- [ ] Update recovery commands, delivery prerequisites and retry instructions,
|
||||
and token environment/file precedence. 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.
|
||||
Check future-note guidance for module-specific full tags and immutable forge
|
||||
links; do not rewrite published notes to adopt the new workflow.
|
||||
- [ ] Verify delivery profile routing and operation forwarding with controlled
|
||||
processes. Rely on upstream tests for Gitea authentication, HTTP writes, and
|
||||
content reconciliation rather than adding a duplicate local delivery engine
|
||||
suite. No real token or hosted writes are needed for these migration checks.
|
||||
- [ ] 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, followed
|
||||
by a separate hosted-delivery operation. Confirmed source publication remains
|
||||
the source-release completion point; hosted-delivery failure is reported and
|
||||
handled separately.
|
||||
|
||||
## 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.
|
||||
The specific forbidden token path and page-only delivery are already selected
|
||||
for implementation and are not part of this open decision.
|
||||
|
||||
**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 executable-storage test machinery and documentation, while
|
||||
the directory ignore rule remains for the token. 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.
|
||||
The implementation plan records the existing integration dependency-version
|
||||
mismatch separately from validation of the current source. This infrastructure
|
||||
sprint does not publish releases or select new library dependency versions.
|
||||
Historical hosted-page backfilling and CI delivery remain separate future
|
||||
choices, not prerequisites for the selected local page-only workflow.
|
||||
|
||||
Reference in New Issue
Block a user