From 7eebe877cf9a21fb4f886f89bbc2089661237fc1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 03:48:28 +0000 Subject: [PATCH] Adopt release policy version 1.6 --- docs/consumers/guide.md | 12 ++++++++++++ docs/oss/attribution.md | 10 ++++++++-- docs/policy/release.md | 43 +++++++++++++++++++++++++++++++++++++---- docs/release.md | 36 +++++++++++++++++++++++++++++++--- 4 files changed, 92 insertions(+), 9 deletions(-) diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 8e391ec..8d15dfc 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -5,6 +5,18 @@ CommandKit's supported Go API is the root `commandkit` package. Start with an commands, and call `App.Execute` with the caller's context and streams. The caller retains process startup, signal handling, and exit mapping. +## Go compatibility + +The consumer minimum is declared in [go.mod](../../go.mod). Its current patch +minimum follows the pinned PromptKit v0.12.0 dependency's `go 1.25.5` requirement; +see that dependency's [module declaration](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/go.mod). + +The [release policy](../policy/release.md#consumer-minimum-and-release-toolchain) +defines support assumptions and versioning for changes to that minimum. +Maintainers select their validation toolchain separately in the +[release procedure](../release.md#release-toolchain). Updating that toolchain's +patch version alone leaves the consumer minimum unchanged. + ## A configuration scope Use [`NewConfigKitScope`](../../config.go) to adapt one ConfigKit loader. The diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 39171c9..bc4dee5 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -196,7 +196,9 @@ Material: `docs/policy/meta.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`, `docs/policy/release.md`, and `docs/policy/oss.md`; the root `AGENTS.md` orientation after the knowledge-graph instructions; and the Policy Reading Guide in `docs/development.md`, adapted for -this repository. +this repository. The release policy uses baseline +`e833faddf120c789a9b45348edaf75720de16348`; the remaining material uses baseline +`d84a38ebab26f048cafbe59a2246700c35d29843`. Copyright (C) 2026 Eric Rakestraw @@ -204,6 +206,10 @@ SPDX-License-Identifier: CC-BY-SA-4.0 License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) | -[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE). +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) | +[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). + +[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348). diff --git a/docs/policy/release.md b/docs/policy/release.md index 4917533..81019fd 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,10 +1,10 @@ # Release Policy -**Base Policy Version:** 1.4 +**Base Policy Version:** 1.6 **Last Updated**: 2026-10-08 -**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) +**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md) ## Purpose @@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an intended source revision under a fresh version. Releases should require little routine intervention, avoid repeated work, and preserve published contents. +Adopt stronger verification or reproducibility requirements through an explicit +project-specific decision justified by the intended audience and support needs. + The repository-specific commands belong in `docs/release.md`. Historical release summaries belong in `docs/releases/`. The procedure must agree with the adopted policy and link to it rather than introduce additional release requirements. @@ -68,7 +71,8 @@ requires a deliberate update to the policy and procedure where needed. For releases at or after `v1.0.0`: - a major release may make intentional incompatible changes; -- a minor release may add backward-compatible behavior; and +- a minor release may add backward-compatible behavior or raise the Go consumer + minimum as described below; and - a patch release may make backward-compatible fixes. Before `v1.0.0`, a minor release may change a documented public, operational, @@ -87,6 +91,36 @@ 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. +## Consumer Minimum And Release Toolchain + +Distinguish the minimum toolchain supported for consumers from the toolchain +maintainers use to build and validate a release. Record the consumer minimum in +the language's standard metadata and explain its support meaning in canonical +documentation. Define the selected release toolchain and its setup commands in +`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific +choices. + +For Go repositories, normally declare the initial stable release of the selected +series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum +when a dependency or an identified correctness fix requires it, and document +the reason. + +For release-policy purposes, successful build and release validation on the +selected Go patch release are sufficient to presume support across that Go +series, subject to the declared consumer minimum and concrete evidence of +incompatibility. Investigate specific compatibility concerns as they arise. + +Use the selected release toolchain for candidate validation and release builds, +including CI jobs performing those tasks. A newer validation patch version alone +leaves the consumer minimum unchanged. + +A minor release may raise the Go consumer minimum, including from one Go series +to the next, both before and after `v1.0.0`. This is an explicit exception to the +backward-compatibility requirement for minor releases. Patch releases preserve +the consumer minimum. Explain an increase's impact and required consumer action +in the release note. Other incompatible changes remain subject to the versioning +rules above. + ## Release Documentation And Preparation Every new release must include `docs/releases/.md` in the tagged @@ -202,7 +236,8 @@ release without replacing its contents or reusing its version. Maintain `docs/release.md` as a short, executable maintainer runbook. It must identify: -1. prerequisites, primary branch, and authoritative remote; +1. prerequisites, selected release toolchain, primary branch, and authoritative + remote; 2. version and release-note preparation; 3. one publication command with its selected local checks and automated guards; 4. declared deliverables, required build targets, and automation responsibilities; diff --git a/docs/release.md b/docs/release.md index a7a3077..faeb2c3 100644 --- a/docs/release.md +++ b/docs/release.md @@ -9,9 +9,9 @@ checksums, or other delivery assets, and it requires no delivery credentials. Use branch `main`, remote `origin`, and the expected effective push endpoint `https://gitea.maximumdirect.net/eric/CommandKit.git`. The profile enforces that -endpoint during publication. The maintainer needs a local Go toolchain -compatible with the module's Go 1.25.5 minimum, Git with push access to `origin`, -and a POSIX shell. +endpoint during publication. The maintainer needs the selected +[release toolchain](#release-toolchain), Git with push access to `origin`, and a +POSIX shell. This procedure follows the [release policy](policy/release.md); the release-note footer follows the [OSS discoverability policy](policy/oss.md#discoverability). @@ -25,6 +25,36 @@ command. The upstream [CLI reference](https://gitea.maximumdirect.net/eric/Relea and [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/consumers/publish.md) own detailed command, profile, and status contracts. +## Release toolchain + +The selected release toolchain is **Go 1.25.5**, matching the current declared +consumer minimum. This keeps candidate validation within the supported Go series. +The [consumer guide](consumers/guide.md#go-compatibility) explains the minimum and +its dependency-based patch requirement; the +[release policy](policy/release.md#consumer-minimum-and-release-toolchain) governs +changes to either selection. + +Use this toolchain for candidate validation and the native ReleaseKit bootstrap, +including CI jobs that perform those tasks. The launcher and ReleaseKit invoke +`go` from `PATH` with `GOTOOLCHAIN=local`, so select that installation in the +shell used for preparation and publication. + +If it is not installed, use the [standard Go installation method](https://go.dev/doc/manage-install). +Ensure Go's executable installation directory (`GOBIN`, or `GOPATH/bin` by +default) is on `PATH` so the downloaded-version wrapper can be invoked: + +```sh +GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.25.5@latest +go1.25.5 download +export PATH="$(go1.25.5 env GOROOT)/bin:$PATH" +hash -r +GOWORK=off GOTOOLCHAIN=local go version +``` + +The final command should identify Go 1.25.5. An existing Go 1.25.5 installation +may be selected directly on `PATH` instead. Toolchain installation and dependency +preparation precede the offline publication checks; they add no validation pass. + ## Prepare and publish a candidate Choose a fresh, unused stable Semantic Version tag in the form