diff --git a/README.md b/README.md index 3d2a5e4..15bdb2f 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,9 @@ tagged-source delivery API, and the `version`, `check`, `publish`, `build`, maintainer procedure and prepared Woodpecker workflow for hosted note-page delivery are documented. ReleaseKit does not declare binary deliverables. -See the [v0.1.0 release note](docs/releases/v0.1.0.md) for the initial baseline -and installation commands. +See the [consumer adoption guide](docs/consumers/adoption.md) to add ReleaseKit +as a versioned Go tool or package dependency, and the +[v0.1.0 release note](docs/releases/v0.1.0.md) for the initial baseline. Run the offline Go test suite from the repository root with: @@ -42,6 +43,8 @@ failure recovery. ## Documentation +- [Consumer adoption](docs/consumers/adoption.md): versioned CLI tool and Go API + dependencies, upgrades, and CI adoption. - [Contributor guide](docs/development.md): orientation, validation, and selective policy reading. - [CLI contract](docs/cli.md): the `version`, `check`, `publish`, `build`, diff --git a/docs/consumers/adoption.md b/docs/consumers/adoption.md new file mode 100644 index 0000000..378c1ab --- /dev/null +++ b/docs/consumers/adoption.md @@ -0,0 +1,53 @@ +# Adopt ReleaseKit + +Use a versioned Go tool dependency when ReleaseKit provides the repository's +release commands. This records the CLI in `go.mod` and keeps it available to +maintainers without adding imports to application or library code. + +## CLI tool dependency + +From the consumer module's root, select the ReleaseKit version to adopt: + +```sh +go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0 +go mod tidy +go tool releasekit version +``` + +Replace `v0.2.0` with the intended release. Go records the executable package in +a `tool` directive and the module version in a `require` directive. The tool +declaration retains the dependency through `go mod tidy`. Commit the resulting +`go.mod` and `go.sum` changes. To upgrade, repeat the command with the chosen +version and review the module changes. + +Go tool dependencies require Go 1.24 or later, together with a toolchain that +satisfies the selected ReleaseKit version and its dependencies. Tools share the +consumer's module graph: their requirements 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). + +Run `go tool releasekit` from within the consumer module to use its selected +version. Follow the [CLI contract](../cli.md) for commands and exit statuses, +and the [configuration reference](../config.md) for the release profile. + +## Go API consumers + +Consumers importing the root `releasekit` API or +[`buildinfo`](runtime-version.md) use ordinary package dependencies. Add the +required imports and select the module version: + +```sh +go get gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0 +go mod tidy +``` + +API consumers can also register the CLI with `go get -tool` as above. Both uses +share the module-selected ReleaseKit version. + +## CI adoption + +The maintained [consumer tag-delivery workflow](delivery.md#woodpecker-tag-workflows) +supports both tool and ordinary package dependencies. It builds ReleaseKit from +the tagged consumer's module 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. diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md index c2920d0..7cf5dfe 100644 --- a/docs/consumers/delivery.md +++ b/docs/consumers/delivery.md @@ -154,7 +154,9 @@ image with Git and a Go toolchain compatible with the consumer module and its selected ReleaseKit version. Choose the patch used for the consumer's release build and validation. The template uses `GOTOOLCHAIN=local`; Go does not download a different toolchain. The tag's `go.mod` must select ReleaseKit as a module -dependency. +dependency. For CLI-only consumers, use the versioned Go tool dependency +described in the [adoption guide](adoption.md). Ordinary package dependencies +also work with this template. Configure the Woodpecker repository secret `releasekit_gitea_token`; the template maps it to `RELEASEKIT_GITEA_TOKEN` for delivery. The repository needs a `delivery` profile. Page-only and binary behavior both use this template; the