commandkit/docs/release.md

CommandKit release procedure

Scope and release order

CommandKit publishes source-only Go module releases. Each module has an independent version and immutable annotated tag. This procedure publishes no hosted release page, binaries, checksums, or other delivery assets. A successful source-tag push is release completion; CI, module proxy availability, and consumer installation are not completion gates.

Publish in dependency order: core, then ckconfig, then ckprompt. The integration modules require the preceding CommandKit releases, so prepare and publish each module only after its CommandKit dependencies are available. A root release runs only the root module's default suite; it need not run suites for independently released integrations.

Use branch main, remote origin, and expected effective push endpoint ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git. The selected module profile enforces the endpoint. The maintainer needs the selected release toolchain, Git push access, and a POSIX shell. This procedure follows the release policy; release-note footers follow the OSS discoverability policy.

ReleaseKit v0.8.0 (go.maximumdirect.net/releasekit) owns candidate validation, publication guards, tag creation, tag publication, and outcome reporting. Its pinned public contracts are the CLI reference, profile reference, and publication guide. The repository selects one default module suite per invocation. The launcher bootstraps the native tool into ignored .releasekit/ storage and delegates to its publish command.

Release toolchain

The selected release toolchain is Go 1.26.8. Each module declares a consumer minimum of Go 1.26.0. Maintainers use Go 1.26.8 for dependency preparation, candidate validation, and the ReleaseKit bootstrap. The consumer guide and release policy describe these selections.

Select Go 1.26.8 on PATH; the launcher uses GOTOOLCHAIN=local. If needed, install it with the standard Go tools:

GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.26.8@latest
go1.26.8 download
export PATH="$(go1.26.8 env GOROOT)/bin:$PATH"
hash -r
GOWORK=off GOTOOLCHAIN=local go version

Modules, versions, notes, and shared files

Select exactly one module with the launcher:

Selector	Physical module directory	Release note	Full tag
core	repository root	docs/releases/<version>.md	<version>
ckconfig	integrations/ckconfig	integrations/ckconfig/docs/releases/<version>.md	integrations/ckconfig/<version>
ckprompt	integrations/ckprompt	integrations/ckprompt/docs/releases/<version>.md	integrations/ckprompt/<version>

Use a fresh stable semantic version (vMAJOR.MINOR.PATCH) for the selected module. Before v1.0.0, a minor release may change a documented contract when its note explains the impact and consumer action. Never reuse a published version. Each release note starts with a product title and exact version, gives a proportionate summary and compatibility guidance, and ends with immutable links to that module's local grant, license, and attribution paths. The full tag in each URL includes the integration directory where applicable. Future tag URLs need not resolve before publication.

All three release profiles explicitly select the repository-root COPYRIGHT, LICENSE, and docs/oss/attribution.md through validation.shared_files. ReleaseKit requires these committed files to exist in the candidate even when no optional file checks are enabled. The list does not enable content checks or expand Go validation scope; see the pinned profile reference.

Each integration also distributes its own COPYRIGHT, LICENSE, and docs/oss/attribution.md. These module-local materials are separate from the explicit root shared-file list and remain subject to the OSS policy. Automatic module file inputs include applicable module-local files and stop at independent nested-module boundaries. Their inclusion does not itself enable license or content validation.

The current profiles enable no optional file checks or additional product checks. Publication runs the selected module's standard offline suite and ReleaseKit's candidate/note and publication guards. The profiles select their physical module directory while using the same repository and endpoint.

Prepare and publish one candidate

Prepare dependencies in the selected module before the candidate is finalized. Do this after the preceding CommandKit module has been published and before the selected candidate suite is run. For core, run the command at the repository root; for integrations, run it from that module directory. Commit any resulting go.mod or go.sum changes with the release candidate. The sum files must reflect dependencies actually downloaded for that module; do not fabricate future sums.

Then commit the selected module's release note and all intended candidate changes on main, and publish the candidate commit to origin. Set one selector, module directory, and version from the table above, then run:

module_dir=.
module_selector=core
module_version=v0.2.0
(cd "$module_dir" && GOWORK=off GOTOOLCHAIN=local go mod download)
# Commit reviewed dependency changes and the selected module's note on main.
git push origin HEAD:refs/heads/main
./scripts/release "$module_selector" "$module_version"

Run only the command for the selected module. Its profile runs the complete offline deterministic default suite once for that module, checks candidate and remote guards, creates the annotated tag from the matching note, and pushes only that full tag. check is available for diagnosis and is not a required pre-publication command. The launcher does not push main; publish the candidate commit first. Successful source publication does not wait for CI, proxy availability, or downstream installation.

Completion and ambiguous publication

A successful push to the expected endpoint completes the source release. ReleaseKit also attempts to save private publication evidence under the repository's Git common directory, shared by linked worktrees. It reports the saved record path or a recording warning separately from publication status; a storage failure does not change publication status. Records can contain credential-bearing endpoints. Retain them privately while recovery is needed and remove them when their recovery value expires; retention is maintainer-owned.

On an ambiguous result, use the recovery command printed for that invocation's saved record. To discover records and explicitly select the matching attempt, the bootstrapped executable can also be used from the repository root:

./.releasekit/bin/releasekit publication-attempts --repo .
./.releasekit/bin/releasekit reconcile --record /absolute/path/to/attempt.json

Replace the example record path with the saved path for the intended attempt. Discovery lists local evidence without querying remotes or selecting an attempt. Reconciliation observes the recorded endpoint, full tag, and tag object without rerunning candidate validation or changing tags. It distinguishes confirmed publication, current absence, conflict, and an unresolved observation. Current absence does not prove that a version was never published. The pinned CLI reference owns recovery statuses and structured output; the publication guide describes record storage and recovery entry points.

If no usable record was saved, use the exact endpoint, full tag, and annotated tag object reported by that invocation. Query only that exact tag ref at the captured endpoint. An exact tag-object match confirms publication, a different object is a conflict, successful output without the ref shows current absence, and a failed query leaves the result unresolved. Do not infer the captured endpoint's state from another remote or a rewritten URL. Resolve unknown publication state before retrying.

ReleaseKit may retain a local tag after a failed push. Remove an unpublished local tag only after proving absence at the captured endpoint and confirming that the tag was never published or used by another release channel. Never move, overwrite, recreate, or delete a published tag. Resolve conflicts with a fresh version; corrections to published source require a new version.