base-layer/releasekit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Include recovery handoffs in the host launcher roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 00:39:01 +00:00
parent b1ce5bf976
commit 373f7a69cd
1 changed files with 40 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/roadmap/host-native-launchers.md
View File

@@ -4,10 +4,11 @@ Status: planned; implementation pending.
## Purpose ## Purpose
Make ReleaseKit's maintained consumer launchers prepare and execute the release Make ReleaseKit's maintained launchers and generated recovery commands prepare
tool for the maintainer's host when inherited `GOOS` and `GOARCH` select a and execute the release tool for the maintainer's host when inherited `GOOS`
different application target. Centralize the recipe and regression coverage so and `GOARCH` select a different application target. Centralize the recipe and
consumers can retain small launchers and product-specific wiring tests. regression coverage so consumers can retain small launchers and product-specific
wiring tests.
This is a launcher correctness improvement. It requires no public bootstrap API, This is a launcher correctness improvement. It requires no public bootstrap API,
validation option, or test-helper package. This roadmap selects no release version validation option, or test-helper package. This roadmap selects no release version
@@ -32,6 +33,13 @@ launcher. The [single-module CI template](../../examples/woodpecker/tag-delivery
and [multi-module CI template](../../examples/multi-module/woodpecker.yml) also and [multi-module CI template](../../examples/multi-module/woodpecker.yml) also
invoke the selected tool without explicit host-target normalization. invoke the selected tool without explicit host-target normalization.
The [maintainer launcher](../../scripts/release),
[source delivery template](../../examples/woodpecker/releasekit-source-delivery.yml),
and [manual delivery retry](../release.md) build and execute the tool with the
same inherited-target assumption. The CLI's [generated recovery command](../../cmd/releasekit/main.go)
inherits the target from the shell where it is run, and [recovery dependency
preparation](../../internal/gotool/recovery.go) also inherits the target.
Existing [launcher tests](../../cmd/releasekit/multi_module_example_test.go) Existing [launcher tests](../../cmd/releasekit/multi_module_example_test.go)
exercise synthetic module selection, publication arguments, child statuses exercise synthetic module selection, publication arguments, child statuses
0 through 3, and preservation of source module metadata. Those fixtures provide 0 through 3, and preservation of source module metadata. Those fixtures provide
@@ -39,11 +47,12 @@ the starting point for foreign-target regression coverage.
## Targeted end state ## Targeted end state
Maintained consumer launchers obtain `GOHOSTOS` and `GOHOSTARCH` from the selected Maintained launchers and module-based recovery use `GOHOSTOS` and `GOHOSTARCH`
Go toolchain and use them as `GOOS` and `GOARCH` while preparing and running from the selected Go toolchain as `GOOS` and `GOARCH` while preparing and running
ReleaseKit. The tool executes on that host even when the caller was working with ReleaseKit. The tool executes on that host even when the caller was working with
a foreign application target. Normalize before target-dependent dependency a foreign application target. Normalize before target-dependent dependency
inspection as well as tool execution. inspection as well as tool execution. Generated recovery commands select the
host when run, using the Go toolchain that will execute the command.
Application targets continue to come from existing release profiles. The Application targets continue to come from existing release profiles. The
launcher's host selection preserves module-selected tool versions, profile and launcher's host selection preserves module-selected tool versions, profile and
@@ -78,18 +87,24 @@ for host-query failures. Avoid hard-coded host values or a new bootstrap layer.
**Rationale:** The same inherited-target failure can affect local and CI tool **Rationale:** The same inherited-target failure can affect local and CI tool
execution. Maintained recipes should give consumers consistent behavior. execution. Maintained recipes should give consumers consistent behavior.
**Target:** The minimal adoption launcher and consumer CI templates select the **Target:** The adoption example, consumer and maintainer launchers, CI
host target when preparing and invoking ReleaseKit. templates, and generated recovery commands select the host target when
preparing and invoking ReleaseKit.
**Work:** Apply the same small normalization recipe to the adoption example and **Work:** Apply the same small normalization recipe to the adoption example and
the single-module and multi-module CI templates. Preserve tag verification before the single-module and multi-module CI templates. Preserve tag verification before
bootstrap, tagged module selection, profile routing, credentials, and temporary bootstrap, tagged module selection, profile routing, credentials, and temporary
metadata handling. Review other maintained executable bootstrap examples for the metadata handling. Apply host selection to the maintainer launcher, source
same target assumption and align affected paths. Update the multi-module README delivery template, and manual delivery retry. Update the multi-module README
and consumer guidance to explain host selection and profile-owned application and consumer guidance to explain host selection and profile-owned application
targets. Document that consumers adopt the corrected launcher or template; a targets. Document that consumers adopt the corrected launcher or template; a
module dependency upgrade alone does not rewrite their copied scripts. module dependency upgrade alone does not rewrite their copied scripts.
Apply host selection to module-based recovery dependency preparation and to the
Go invocation printed by `publish`. Preserve registered-tool selection, private
bootstrap metadata for API-only consumers, the native executable fallback,
explicit record selection, and recovery exit statuses.
### 3. Extend existing behavioral coverage ### 3. Extend existing behavioral coverage
**Rationale:** Successful execution under a foreign target directly protects **Rationale:** Successful execution under a foreign target directly protects
@@ -106,10 +121,14 @@ that statuses 0, 1, 2, and 3 propagate. Check unchanged source module files and
existing temporary bootstrap cleanup. Reuse unaffected tests rather than adding existing temporary bootstrap cleanup. Reuse unaffected tests rather than adding
a parallel launcher or publication-engine suite. a parallel launcher or publication-engine suite.
Cover affected CI/bootstrap recipes through their existing test harnesses where Verify host selection at the dependency inspection step itself, using a
practical, including normalization before dependency inspection. Preserve host-specific fixture or an environment assertion at `go list -deps`. Cover
profile-selected application targets. Use synthetic local tools and test-owned affected CI/bootstrap recipes through their existing test harnesses where
module caches under the [fixture-isolation guidance](../development.md#testing-synthetic-modules). practical. Extend the existing handoff tests to exercise recovery preparation
under a foreign target, then run the printed command under a foreign target in
a separate invocation. Preserve profile-selected application targets. Use
synthetic local tools and test-owned module caches under the
[fixture-isolation guidance](../development.md#testing-synthetic-modules).
The regression needs no actual publication, hosted service, or external platform The regression needs no actual publication, hosted service, or external platform
runner. Choose a representative supported foreign target instead of introducing runner. Choose a representative supported foreign target instead of introducing
a platform matrix. a platform matrix.
@@ -132,11 +151,12 @@ that protect their own behavior.
## Completion evidence ## Completion evidence
Completion requires host execution under a foreign target, preserved selected Completion requires host selection before dependency inspection and successful
tool identity and arguments, child-status forwarding, unchanged source metadata, host execution under a foreign target, including for generated recovery commands.
and existing cleanup behavior. The maintained local and CI recipes and adoption Preserve selected tool identity and arguments, child-status forwarding, unchanged
guidance must use the same host-selection approach. Application build targets source metadata, and existing cleanup behavior. The maintained local and CI
must retain their existing profile-driven behavior. recipes and adoption guidance must use the same host-selection approach.
Application build targets must retain their existing profile-driven behavior.
There are no significant open design decisions for this scope. Exact shell There are no significant open design decisions for this scope. Exact shell
variable names and fixture arrangement can be selected during implementation. variable names and fixture arrangement can be selected during implementation.