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. A successful source-tag push completes the source release. A separate local delivery command can publish a Gitea release page; there are no binaries, checksums, or other delivery assets. 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.9.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, the publication guide, and the delivery guide. The repository selects one default module suite per invocation. The launcher uses the root module’s registered tool with native host settings and read-only module metadata.

Release toolchain

The selected release toolchain is Go 1.27.0. Core and ckprompt declare a consumer minimum of Go 1.26.0; ckconfig requires Go 1.27.0. Maintainers use Go 1.27.0 for dependency preparation, candidate validation, and ReleaseKit execution. The consumer guide and release policy describe these selections.

Select Go 1.27.0 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.27.0@latest
go1.27.0 download
export PATH="$(go1.27.0 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. For future notes, use https://forge.maximumdirect.net/base-layer/commandkit/src/tag/FULL_TAG/ followed by the repository-relative path: COPYRIGHT, LICENSE, and docs/oss/attribution.md for core, or those paths prefixed with the selected integration directory. 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. The list does not 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.

Each profile selects Go formatting, Markdown links, workspace-file and local replacement checks, and forbids the committed .releasekit/gitea-token path. These upstream checks inspect committed inputs; module file selection stops at independent module boundaries, while the forbidden path covers the repository. They do not replace domain review. Publication also runs the selected module’s standard offline suite and ReleaseKit’s candidate/note and publication guards.

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 module directory and version from the table above, then run the corresponding publication command:

module_dir=.
(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 core vX.Y.Z
# For integrations use: ./scripts/release ckconfig vX.Y.Z
# or: ./scripts/release ckprompt vX.Y.Z

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. ./scripts/releasekit core check vX.Y.Z is an optional diagnostic, not a required pre-publication step: publication repeats validation. Use the relevant integration selector and its version when diagnosing that module. Inspect the registered tool with ./scripts/releasekit version. 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 shared helper can also be used:

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

Replace the example record path with the saved path for the intended attempt. Relative record paths resolve from the repository root. 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.

Hosted delivery

After source publication, check out the original tagged source with a clean worktree and index, then deliver the selected module's page:

./scripts/releasekit core deliver vX.Y.Z
# Or use ckconfig or ckprompt with that module's semantic version.

The profile derives the full module-specific tag from the version. Delivery uses the checked-in release note as a page-only body and reports its own outcome and URL separately from source publication. Retry later from the same original tagged source. The pinned delivery guide owns delivery and retry behavior.

A nonblank RELEASEKIT_GITEA_TOKEN takes precedence over the repository-relative .releasekit/gitea-token file. Keep the credential directory ignored and retain its local contents. Credentials and Gitea availability do not gate source publication.