From 1613ff95cab60581de5d86f6e9e2a3cc091a44a0 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 15:13:39 +0000 Subject: [PATCH] Require downstream integration releases for dependency updates --- docs/policy/release.md | 18 +++++++++++++++++- docs/release.md | 38 +++++++++++++++++++++++++++++--------- 2 files changed, 46 insertions(+), 10 deletions(-) diff --git a/docs/policy/release.md b/docs/policy/release.md index f1d99a6..d1c2da4 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.6 -**Last Updated**: 2026-10-11 +**Last Updated**: 2026-11-08 **Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md) @@ -96,6 +96,22 @@ Additional compatibility promises and deliberate exceptions belong in the adopted policy or canonical contract documentation. Release notes explain changes; they do not redefine current compatibility contracts. +### CommandKit downstream dependency alignment + +Each new core or integration release requires dependency updates and new releases +of all downstream CommandKit-owned integration modules, following direct and +transitive dependencies. Each affected integration advances at least its minor +version to incorporate the dependency updates, even when the initiating release +is a patch. Use a major release where the compatibility rules above require it. +Versions remain independent and need not match across modules. + +A module with no downstream CommandKit integrations may release independently; +its release does not require new versions of its dependencies. This policy does +not require releases of external consuming applications. The +[runbook](../release.md#scope-and-release-order) owns dependency-order sequencing. +Downstream releases are required follow-up work, not additional completion gates +for an already published source release. + ## Consumer Minimum And Release Toolchain Distinguish the minimum toolchain supported for consumers from the toolchain diff --git a/docs/release.md b/docs/release.md index 2ca0470..4221ec5 100644 --- a/docs/release.md +++ b/docs/release.md @@ -9,11 +9,28 @@ 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. +Plan the initiating release and all downstream integration releases required by +the [dependency-alignment policy](policy/release.md#commandkit-downstream-dependency-alignment). +That policy sets the minimum version bump for affected integrations; select +each module's version independently according to its compatibility impact. + +| Initiating release | Required downstream releases, in order | +| --- | --- | +| Core | `ckconfig`, then `ckprompt` | +| `ckconfig` | `ckprompt` | +| `ckprompt` | None with the current dependency graph | + +As integrations are added, follow their actual dependencies to include every +affected downstream integration. Publish dependencies before their consumers. +Prepare each integration after its updated CommandKit dependencies are published, +incorporating all of those versions in one candidate. For a core update, release +`ckprompt` once after both core and `ckconfig`; it does not need separate releases +for each dependency bump. Unaffected dependencies do not need new releases. + +Track any remaining downstream releases as pending coordination work. Each +successful source-tag push still completes that module's release; a downstream +failure does not undo it or authorize replacing its tag. A root release runs +only the root module's default suite; each downstream release runs its own suite. Use branch `main`, remote `origin`, and expected effective push endpoint `ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. The selected @@ -98,14 +115,17 @@ 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. +Do this after any CommandKit dependency releases required by the coordinated +update have 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. Before downloading dependencies, update each integration to the newly published CommandKit versions. `go mod download` downloads the versions already selected; it does not upgrade requirements. Replace the version placeholders below with -the actual published versions, which may differ between modules: +the actual published versions, which may differ between modules. When a +dependency is not being released in this update, use its current selected +release; a `ckconfig`-initiated update does not require a new core release: ```sh # After publishing core, prepare ckconfig from its module directory.