From 0269648429134cae2a1aa73ba0e2329884ccb7d0 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 00:54:44 +0000 Subject: [PATCH] Document host-native release launchers --- docs/cli.md | 3 ++- docs/consumers/adoption.md | 11 ++++++++++- docs/consumers/delivery.md | 3 ++- docs/internal/gotool.md | 3 +++ docs/roadmap/implementation.md | 2 ++ examples/multi-module/README.md | 24 +++++++++++++++++++++--- 6 files changed, 40 insertions(+), 6 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index a7935db..b89005b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -154,7 +154,8 @@ uses a persistent native executable when available. Recognized temporary Go-buil executables provide no native fallback after their driver exits. Command preparation has its own bounded context after a failed publication, so publication cancellation permits preparing the later invocation. Each entry point preserves -the recovery exit status. +the recovery exit status. Generated Go-tool handoffs select the host target when +they run, independently of inherited cross-compilation settings. If the selected entry point becomes unavailable, use another supported ReleaseKit CLI with the saved record. diff --git a/docs/consumers/adoption.md b/docs/consumers/adoption.md index 3f33b50..d304e4d 100644 --- a/docs/consumers/adoption.md +++ b/docs/consumers/adoption.md @@ -12,7 +12,6 @@ From the consumer module's root, select the ReleaseKit version to adopt: : "${RELEASEKIT_TOOL_VERSION:?Set the released ReleaseKit version to adopt}" go get -tool "go.maximumdirect.net/releasekit/cmd/releasekit@${RELEASEKIT_TOOL_VERSION}" go mod tidy -go tool releasekit version ``` Select a release that implements the API, profile, and workflow you are adopting. @@ -39,9 +38,15 @@ A launcher invoked from that module can forward commands directly: ```sh #!/bin/sh +releasekit_host_os=$(go env GOHOSTOS) || exit $? +releasekit_host_arch=$(go env GOHOSTARCH) || exit $? +export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" exec go tool releasekit "$@" ``` +Save this launcher as `releasekit` and run `./releasekit version` from the +selected module to verify registration. It preserves the consumer's workspace +and toolchain settings while selecting the host for the executable. For a launcher callable from other directories, first change to its consumer module directory. Follow the [CLI contract](../cli.md) for commands and exit statuses, and the [configuration reference](../config.md) for the release profile. @@ -108,6 +113,10 @@ selection, so the committed module files also govern CI delivery and retries. Registering the CLI as a tool is sufficient for consumers that use ReleaseKit only for maintainer commands. +Update copied launchers and workflow templates separately when upgrading the +module dependency. ReleaseKit tests the generic bootstrap; consumer wiring tests +can focus on selectors and profile mapping. Profiles continue to select +application build targets. Upgrade the module-selected tool and workflow together. For a tag created before that upgrade, retry with the workflow matching the tool recorded at that tag. Keep its immutable module files and tag intact. See the diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md index 6275758..c6a9a5a 100644 --- a/docs/consumers/delivery.md +++ b/docs/consumers/delivery.md @@ -293,7 +293,8 @@ identify an annotated tag object or a commit. The template requires the resolved commits to match, checks out that commit detached, and confirms the source tree is clean. It then copies the tagged `go.mod` and any `go.sum` to a temporary directory outside the checkout. `go list -m` confirms that the module selects -ReleaseKit. The template adds its CLI tool declaration to that temporary copy +ReleaseKit. The template selects the host Go target before preparing and running +the CLI. The template adds its CLI tool declaration to that temporary copy and prepares tool dependencies with `go list -deps`. It then uses `go tool -modfile=... releasekit` to build, cache, and run the selected tool with `CI_WORKSPACE`, the resolved event commit, and `CI_COMMIT_TAG`. The tagged module diff --git a/docs/internal/gotool.md b/docs/internal/gotool.md index 6850297..2aeb03a 100644 --- a/docs/internal/gotool.md +++ b/docs/internal/gotool.md @@ -15,6 +15,9 @@ requirements, versioned replacements, and checksums. Local replacements resolve against their original module directory before relocation. The original main module remains a local replacement, including when releasing ReleaseKit itself. The private root provides tool resolution independently of consumer vendoring. +API-only preparation discovers the host target for dependency inspection. The +returned invocation carries its directory and tool arguments; the CLI's later +shell command selects the host again when it runs. The CLI formats the later invocation using a separate bounded context after publication failure. It falls back to a persistent native executable when module selection is unavailable or preparation fails, and excludes recognized temporary diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1ed41dd..2027539 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -160,6 +160,8 @@ checks in Stage 6. ## Stage 6: Align consumer guidance and verify the sprint +**Completed.** + 1. In the [adoption guide](../consumers/adoption.md), make the minimal launcher use the Stage 1 recipe followed by `exec go tool releasekit "$@"`. Run it from the selected module, retaining that consumer's workspace and diff --git a/examples/multi-module/README.md b/examples/multi-module/README.md index f161ca4..776a39e 100644 --- a/examples/multi-module/README.md +++ b/examples/multi-module/README.md @@ -126,9 +126,27 @@ source and each selected product's module-local release note, then commit the fixture and run the source-selected tool without publishing: ```sh -go tool releasekit check --config releasekit-root.json v1.2.3 -go -C integrations/ckconfig tool releasekit check --config releasekit-ckconfig.json v1.2.3 -go -C integrations/core/v2 tool releasekit check --config releasekit-core-v2.json v2.1.0 +( + cd . || exit $? + releasekit_host_os=$(go env GOHOSTOS) || exit $? + releasekit_host_arch=$(go env GOHOSTARCH) || exit $? + export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" + go tool releasekit check --config releasekit-root.json v1.2.3 +) +( + cd integrations/ckconfig || exit $? + releasekit_host_os=$(go env GOHOSTOS) || exit $? + releasekit_host_arch=$(go env GOHOSTARCH) || exit $? + export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" + go tool releasekit check --config releasekit-ckconfig.json v1.2.3 +) +( + cd integrations/core/v2 || exit $? + releasekit_host_os=$(go env GOHOSTOS) || exit $? + releasekit_host_arch=$(go env GOHOSTARCH) || exit $? + export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" + go tool releasekit check --config releasekit-core-v2.json v2.1.0 +) ``` These commands use the repository-root profile paths even when invoked from a