diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 2dac3ab..d10b69c 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -19,6 +19,20 @@ The following Go fragments are illustrative and omit surrounding package, import, and error-handling code. Use the maintained examples for complete programs. +## Go Compatibility + +The `go` directive in the selected release's [module metadata](../../go.mod) +declares its minimum supported consumer Go version. Maintainers build and +validate releases with the locally selected Go patch release; the minimum +does not simply track that patch version. + +Successful release validation on the selected patch is sufficient to presume +support across its Go series, subject to the declared minimum and concrete +evidence of incompatibility. Specific compatibility concerns are investigated +as they arise. Minor releases may raise the minimum; patch releases preserve +it. Release notes explain increases and any required consumer action. See the +[release policy](../policy/release.md#consumer-minimum-and-release-toolchain). + ## Construct An Engine Create an engine with [`NewEngine`](../../engine.go). Select each directory diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 452cf5f..bcf46d2 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -6,16 +6,24 @@ Material: policy documents under `docs/policy/` and the Policy Reading Guide in `docs/development.md`, adapted for this repository; root `AGENTS.md`, copied without modification from upstream `agents/AGENTS.md`. +The release policy uses upstream commit +`e833faddf120c789a9b45348edaf75720de16348`; the remaining material uses +`d84a38ebab26f048cafbe59a2246700c35d29843`. + Copyright (C) 2026 Eric Rakestraw 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). + ## ConfigKit Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.5.0`. diff --git a/docs/policy/release.md b/docs/policy/release.md index a64154e..b36e172 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. @@ -59,7 +62,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, @@ -71,14 +75,45 @@ 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. -## Release Documentation +## 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 source tree. Use the complete version tag as the filename and begin with a title containing the product name and that exact version. Include a short summary and any relevant compatibility impact or upgrade -instructions. Keep the note proportionate to the change. +instructions. Choose sections suited to the release and keep the note +proportionate to the change. Keep exact current contracts in their canonical documents and update affected documentation with the behavior change. Link to those documents from the note @@ -185,7 +220,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; @@ -209,17 +245,18 @@ annotated stable SemVer tags. It has no binaries, hosted download pages, or asynchronous deliverables. The source commit is pushed through main before the tag. The [release procedure](../release.md) owns commands and recovery. -Release preparation advances Promptkit's `go.mod` Go requirement to the initial -stable release of the latest Go series available in the development environment -(for example, `go 1.26.0`). Use a higher patch minimum when required by a -dependency or a specific correctness fix, rather than recording the maintainer's -current patch solely because it was used to build the release. +Release preparation uses the latest Go installation available in the development +environment to build the maintainer release executable and validate the +candidate, including the consumer examples. Keep that same local toolchain +active throughout those operations. -Use the latest locally available patch in that series for candidate validation -and to build any maintainer release executable. Keep that same local toolchain -active throughout those operations. Commit the module update before validating -the final candidate, and describe a raised minimum Go requirement and its -compatibility impact in the release note under the versioning policy above. +For a minor release, advance Promptkit's consumer minimum to the initial stable +release of that Go series, retaining a higher patch minimum when required by a +dependency or an identified correctness fix. Patch releases preserve the +existing consumer minimum. Commit any module update before validating the final +candidate. The [release procedure](../release.md#prepare-the-candidate) owns +setup commands, and the consumer guide explains +[Go compatibility](../consumers/pkg-promptkit.md#go-compatibility). Use a title containing `Promptkit` and the exact version, followed by a short summary and any relevant compatibility impact or upgrade instructions. The diff --git a/docs/release.md b/docs/release.md index c258ef1..4982fa8 100644 --- a/docs/release.md +++ b/docs/release.md @@ -12,12 +12,17 @@ Required tools are Git, Go with race-detector support, POSIX shell, and Python Use the latest Go installation available locally for the release tool, the candidate validation, and the maintained examples. Make it the active `go` -command and record its version. Set Promptkit's consumer minimum to the initial -stable release of that Go series before committing the candidate: +command and record its version: ```sh export GOTOOLCHAIN=local go version +``` + +For a minor release, advance Promptkit's consumer minimum to the initial stable +release of that Go series before committing the candidate: + +```sh release_go_version=$(go env GOVERSION) release_go_series=${release_go_version#go} release_go_series=${release_go_series%.*} @@ -25,9 +30,14 @@ go mod edit "-go=${release_go_series}.0" ``` For example, Go 1.26.8 normally results in `go 1.26.0`. Keep a higher patch -minimum if a dependency or correctness fix requires it. Prepare module caches -before validation; this may update `go.sum` and belongs before the candidate -commit: +minimum if a dependency or identified correctness fix requires it. For a patch +release, leave the consumer minimum unchanged; using a newer validation +toolchain does not itself raise that minimum. If the candidate needs a higher +minimum, prepare a minor release instead. See the +[consumer-minimum policy](policy/release.md#consumer-minimum-and-release-toolchain). + +Prepare module caches before validation; this may update `go.sum` and belongs +before the candidate commit: ```sh GOTOOLCHAIN=local go mod download