|
|
|
|
@@ -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/<version>.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
|
|
|
|
|
|
