diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 0b17d9a..023fc8a 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -29,6 +29,9 @@ License and notices: [MIT](licenses/MIT.txt) | Material: policy documents under `docs/policy/`, the root `AGENTS.md` orientation, and the Policy Reading Guide in `docs/development.md`, adapted for this repository. +The release policy incorporates revision `e833faddf120c789a9b45348edaf75720de16348`; +the remaining material incorporates revision +`d84a38ebab26f048cafbe59a2246700c35d29843`. Copyright (C) 2026 Eric Rakestraw @@ -38,4 +41,9 @@ 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). -[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). +Release-policy notices: +[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE). + +[Release-policy source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md) | +[Other policy material source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). diff --git a/docs/policy/release.md b/docs/policy/release.md index 1abfdd9..cfd23fe 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. @@ -69,7 +72,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, @@ -81,34 +85,42 @@ 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. -## Go Minimum And Release Toolchain +## Consumer Minimum And Release Toolchain ReleaseKit provides reasonable support for routine build and release needs, -following [ADR 0002](../adr/0002-routine-releases.md). Its Go support policy relies -on upstream compatibility commitments and verification proportionate to those -needs. +following [ADR 0002](../adr/0002-routine-releases.md). Distinguish the minimum Go +toolchain supported for consumers from the toolchain maintainers use to build +and validate a release. The consumer minimum belongs in [go.mod](../../go.mod); +the [maintainer runbook](../release.md) defines the selected release toolchain +and its setup commands. Select the Go series during release preparation. When advancing the consumer minimum, use the latest locally available stable series and record its initial stable version in `go.mod`, such as `go 1.26.0`. Use a higher patch minimum when -a dependency requirement or identified correctness fix requires it. Minimum -increases follow the versioning and compatibility rules above and are explained -in the release note. +a dependency requirement or identified correctness fix requires it, and document +the reason. Build the maintainer release executable and validate the candidate with the same latest locally available patch of the selected series. Keep that toolchain active throughout preparation, tool bootstrap, and validation, using local -toolchain selection. Maintained CI images follow the chosen build toolchain. -The patch used for these operations is separate from the consumer minimum. +toolchain selection. CI jobs performing release builds and validation use the +selected toolchain; maintained CI images follow that choice. A newer validation +patch version alone leaves the consumer minimum unchanged. -Successful build and release validation on that patch serve as sufficient -evidence of support from the series' initial stable release through subsequent -patch releases, subject to known dependency requirements or correctness issues. +For release-policy purposes, successful build and release validation on that +patch are sufficient to presume support across the selected Go series, subject +to the declared consumer minimum and concrete evidence of incompatibility. This relies on Go's [release policy](https://go.dev/doc/devel/release#policy) and -[compatibility commitments](https://go.dev/doc/go1compat). Additional -patch-specific validation is warranted by concrete evidence; routine releases -require no patch-version matrix. Record the actual validation toolchain in the -release evidence. +[compatibility commitments](https://go.dev/doc/go1compat). Investigate specific +compatibility concerns as they arise. Routine releases require no patch-version +matrix. Record the actual validation toolchain in the release evidence. + +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 @@ -161,8 +173,8 @@ checks when their distinct protection justifies their cost. A one-time migration check must not silently become a permanent release requirement. Release tests must not require real credentials, mutable application services, -paid APIs, or live service probes. The procedure may describe dependency -preparation separately from offline validation. +paid APIs, live service probes, or inference calls. The procedure may describe +dependency preparation separately from offline validation. Avoid duplicate validation across release phases. Successful checks for the same final candidate need not be repeated solely to satisfy another phase; @@ -229,7 +241,8 @@ release without replacing its contents or reusing its version. Create and maintain `docs/release.md` with the first working publication command 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 a44a134..2862240 100644 --- a/docs/release.md +++ b/docs/release.md @@ -22,7 +22,7 @@ go version ``` Record the reported version with the validation results. The -[Go support policy](policy/release.md#go-minimum-and-release-toolchain) owns +[Go support policy](policy/release.md#consumer-minimum-and-release-toolchain) owns series selection, consumer minima, patch exceptions, and validation scope. The maintained [source-delivery image](../examples/woodpecker/releasekit-source-delivery.yml) and [consumer template image](../examples/woodpecker/tag-delivery.yml) follow the