From ec674965698fb18818a2ce4b1e8e63421de83fb6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 01:24:16 +0000 Subject: [PATCH] Align source and standalone tool instructions --- README.md | 4 +++- docs/cli.md | 2 ++ docs/consumers/adoption.md | 2 ++ docs/consumers/delivery.md | 19 +++++++++++++++---- docs/roadmap/remediation.md | 2 ++ 5 files changed, 24 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6abda0c..2bd152c 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,9 @@ Run the offline Go test suite from the repository root with: go test ./... ``` -The version command prints ReleaseKit's version: +The version command prints ReleaseKit's version. For the `go run` examples +below, [select the Go host target](docs/consumers/adoption.md#select-the-go-host-target) +if your shell is set to cross-compile. ```sh go run ./cmd/releasekit version diff --git a/docs/cli.md b/docs/cli.md index e5f19f5..301e039 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -4,6 +4,8 @@ ReleaseKit currently provides eight commands. The exit statuses below belong to the native executable. `go run` examples are convenient for source execution, but the Go driver maps a nonzero child exit status to 1. Use the built executable or `./scripts/release` for publication when distinct statuses are needed. +For the `go run` examples, [select the Go host target](consumers/adoption.md#select-the-go-host-target) +before running from a shell set to cross-compile. Print the executable version: diff --git a/docs/consumers/adoption.md b/docs/consumers/adoption.md index 6b67f4d..111864d 100644 --- a/docs/consumers/adoption.md +++ b/docs/consumers/adoption.md @@ -32,6 +32,8 @@ participate in dependency version selection and can raise the consumer module's Go minimum. See the [Go tool dependency reference](https://go.dev/ref/mod#go-mod-file-tool). +### Select the Go host target + Run `go tool releasekit` from within the consumer module to use its selected version. Go builds and caches the executable and preserves its exit status. A launcher invoked from that module can forward commands directly: diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md index c6a9a5a..b06b628 100644 --- a/docs/consumers/delivery.md +++ b/docs/consumers/delivery.md @@ -337,10 +337,21 @@ and application artifact compilation retain their separate environments. The normal Go module and build caches are sufficient. Cache mounts may be added as deployment configuration when they help the runner; they are not needed by -the template. A separately installed executable can be installed with -`go install go.maximumdirect.net/releasekit/cmd/releasekit@PIN`, then run -with the same arguments. With the event object available in the CI checkout, -resolve it to its source commit before invocation: +the template. For a standalone installation, replace `PIN` with the desired +version and [select the Go host target](adoption.md#select-the-go-host-target) +for `go install`: + +```sh +( + releasekit_host_os=$(go env GOHOSTOS) || exit $? + releasekit_host_arch=$(go env GOHOSTARCH) || exit $? + export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" + go install go.maximumdirect.net/releasekit/cmd/releasekit@PIN +) +``` + +With the event object available in the CI checkout, resolve it to its source +commit before invoking the installed executable: ```sh expected_commit=$(git -C "$CI_WORKSPACE" rev-parse --verify "${CI_COMMIT_SHA}^{commit}") diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 411e83c..2fa3969 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -141,6 +141,8 @@ semantics and the separate profile selection for built-in builds. ### Align direct source and standalone CI recipes with the launcher guidance +**Completed.** The source examples link to host selection, and the standalone install recipe scopes the same settings to `go install`. Both paths were verified under a foreign target. + **Evidence:** The [README quick start](../../README.md) and [CLI reference](../cli.md) still recommend bare `go run ./cmd/releasekit` for source invocation. The [consumer delivery guide](../consumers/delivery.md#woodpecker-tag-workflows)