releasekit/docs/consumers/adoption.md

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:

: "${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. The vanity module path starts with v0.5.0. Versions through v0.4.2 declare the original module path and use their corresponding historical instructions. The module-release interface requires a release containing that feature; pre-feature versions through v0.3.0 use their corresponding historical interface. 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.

The Go tool dependency feature requires Go 1.24 or later. The current ReleaseKit module declares a Go 1.26.0 minimum, so use Go 1.26.0 or later for the current release. Tool dependencies 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.

Run go tool releasekit from within the consumer module to use its selected version. Follow the CLI contract for commands and exit statuses, and the configuration reference for the release profile.

Go API consumers

Consumers importing the root releasekit API or buildinfo use ordinary package dependencies. Add the required imports and select the module version:

: "${RELEASEKIT_TOOL_VERSION:?Set the released ReleaseKit version to adopt}"
go get "go.maximumdirect.net/releasekit@${RELEASEKIT_TOOL_VERSION}"
go mod tidy

API consumers can also register the CLI with go get -tool as above. Both uses share the module-selected ReleaseKit version.

Migrating from the original module path

Starting with v0.5.0, ReleaseKit's module is go.maximumdirect.net/releasekit. Earlier releases declare gitea.maximumdirect.net/eric/ReleaseKit. The migration is a direct cutover with the existing facade roles and command behavior.

For API consumers, update imports of the root facade and buildinfo to go.maximumdirect.net/releasekit and go.maximumdirect.net/releasekit/buildinfo, including generated code and tests. Select v0.5.0 or a later compatible release using the package-dependency command above. Packages imported through the old and new paths have distinct Go identities; coordinate updates in packages that exchange ReleaseKit facade types. Builders and applications using buildinfo should adopt the new path together so version injection addresses the runtime implementation they use.

For CLI tool consumers, remove the old tool declaration before registering the new CLI package with the tool-dependency command above:

go mod edit -droptool=gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit

Update copied release launchers and Woodpecker workflows so their releasekit_module value is go.maximumdirect.net/releasekit. Use the maintained examples matching the selected tool version. Run go mod tidy after updating imports and tool declarations, review any old-path dependencies retained transitively, and commit the resulting module files with the workflow changes.

Existing consumer tags retain their recorded module files, tool selection, and matching workflows for retries. Apply these migration steps to new consumer revisions. Source repository and hosted release URLs use https://forge.maximumdirect.net/base-layer/releasekit; the vanity path is the Go module identity. The Go consumer minimum remains 1.26.0.

CI adoption

The maintained consumer tag-delivery workflow 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.

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 delivery guide for tagged-source bootstrap and the example's source verification for testing an unreleased checkout in a disposable consumer repository.