From 007eae4ed0c2a7e6e28ffc67761adc956e97e832 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 3 Nov 2026 15:46:20 +0000 Subject: [PATCH] Document release delivery workflow --- docs/development.md | 12 ++--- docs/policy/release.md | 6 ++- docs/release.md | 84 +++++++++++++++++++++++----------- docs/roadmap/implementation.md | 5 +- 4 files changed, 70 insertions(+), 37 deletions(-) diff --git a/docs/development.md b/docs/development.md index e06956a..3590c72 100644 --- a/docs/development.md +++ b/docs/development.md @@ -124,14 +124,10 @@ publication commands. ## Release tooling development -The local publication exercise is opt-in and uses disposable Git repositories. -Prepare the module cache before running it; ordinary tests do not bootstrap or -publish a release: - -```sh -GOWORK=off GOTOOLCHAIN=local go mod download -COMMANDKIT_RELEASE_INTEGRATION=1 GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$' -``` +Run the focused launcher wiring tests with `go test ./scripts`. The release +profiles select upstream checks of committed inputs independently for each +module; these checks do not replace domain review. See the +[release procedure](release.md) for publication, delivery, and recovery. Follow the [local commit policy](policy/agents.md#git-commit-policy). Completed units receive local commits by default, subject to explicit user instructions. diff --git a/docs/policy/release.md b/docs/policy/release.md index 09c92df..b2393cf 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -26,8 +26,10 @@ CommandKit independently versions three source-only Go modules: the root core, `integrations/ckconfig`, and `integrations/ckprompt`. Standard CLI behavior is exposed by consuming applications; CommandKit does not declare binary deliverables or a cross-platform build matrix. ReleaseKit v0.8.0 is selected as -the maintainer publication tool. The [release procedure](../release.md) owns -the selected-module workflow, release order, and repository-specific commands; +the maintainer publication tool. Maintainers may separately deliver page-only +Gitea releases from tagged source; delivery has its own outcome and URL. The +[release procedure](../release.md) owns the selected-module workflow, release +order, and repository-specific commands; the integration adds no application command family or runtime ReleaseKit import. diff --git a/docs/release.md b/docs/release.md index ab82598..a1c7faf 100644 --- a/docs/release.md +++ b/docs/release.md @@ -3,10 +3,11 @@ ## 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. +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 @@ -26,16 +27,17 @@ publication guards, tag creation, tag publication, and outcome reporting. Its pinned public contracts are the [CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/cli.md), [profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md), -and [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/consumers/publish.md). +the [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/consumers/publish.md), +and the [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/consumers/delivery.md). 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. +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.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 +candidate validation, and ReleaseKit execution. The [consumer guide](consumers/guide.md#go-compatibility) and [release policy](policy/release.md#consumer-minimum-and-release-toolchain) describe these selections. @@ -67,14 +69,16 @@ 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. +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 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](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md). +ReleaseKit requires these committed files to exist in the candidate. The list +does not expand Go validation scope; see the pinned [profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md). Each integration also distributes its own `COPYRIGHT`, `LICENSE`, and `docs/oss/attribution.md`. These module-local materials are separate from the @@ -83,10 +87,12 @@ 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. +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 @@ -100,23 +106,27 @@ 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 directory and version from the table above, then run the corresponding +publication command: ```sh 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" +./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. `check` is available for diagnosis and is not a required -pre-publication command. The launcher does not push `main`; publish the +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. @@ -132,14 +142,15 @@ 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: +the shared helper can also be used: ```sh -./.releasekit/bin/releasekit publication-attempts --repo . -./.releasekit/bin/releasekit reconcile --record /absolute/path/to/attempt.json +./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 @@ -163,3 +174,24 @@ 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: + +```sh +./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](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/consumers/delivery.md) +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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 46ad894..a8c2d0a 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Release tooling implementation plan -Status: Stages 1–3 complete; Stages 4–6 pending. +Status: Stages 1–4 complete; Stages 5–6 pending. Follow the stages in integer order. This is one end-to-end sprint: intermediate stages may temporarily leave scripts, tests, and documentation inconsistent. @@ -199,6 +199,9 @@ upstream tests own publication, credential handling, and hosted reconciliation. ## Stage 4: Align current documentation with the implemented workflow +**Completed.** The release procedure, project-specific policy, and developer +guidance describe the new launcher, checks, delivery, and recovery workflow. + Update `docs/release.md`, the CommandKit-specific scope in `docs/policy/release.md`, and release-tooling guidance in `docs/development.md`. Keep adopted general policy text and provenance intact. Change current owners