# Release Policy **Base Policy Version:** 1.6 **Last Updated**: 2026-10-08 **Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md) ## Purpose 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. ## Release Model And Completion A source release identifies one exact committed source revision through an immutable version tag and a version-matched, checked-in release note. The primary release branch is `main` unless the adopted policy specifies otherwise. The procedure must name the authoritative publication remote. A successful push of the intended tag, with its source commit available on the authoritative primary branch, completes the release. The source commit may be pushed before the tag or published together with it through an atomic push. The procedure must choose and document the supported approach. Release commands must finish at successful publication. They must not wait for or poll CI, require successful CI status, inspect downloadable artifacts, or check consumer installation or Go module availability as completion gates. A failed or ambiguous push requires resolving the authoritative remote state before declaring success or retrying; successful pushes do not require a separate remote read-back gate. Repositories may publish source only. Additional binaries, images, packages, checksums, or other declared deliverables may be published asynchronously from the tagged source. The procedure must identify those deliverables and the responsibility of their automation. Published deliverables must be traceable to that source and identify the same version. Track source-release completion and artifact delivery separately. Report delivery failures and optional investigations under artifact-delivery status. ## Versioning And Compatibility Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with no leading zeroes. Prereleases require an explicit adopted policy defining their format and use. The selected version must be unused locally and on the authoritative remote. Do not require queries to every configured remote or publication service. A version known to have already been published must not be reused, even if the normal guards do not inspect that channel. Adding a distribution channel 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 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, configuration, data, integration, or compatibility contract when the release note explains the impact and required consumer action. A patch release must not intentionally break those contracts within its minor line. 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 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. 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 where useful. If annotated tags are used, derive their summary from the checked-in note. Include the release footer defined by the [OSS policy](oss.md#discoverability) in each new release document and preserve it on the hosted download page. The release procedure defines the concrete URLs and publication mechanics. Prepare these links with the release note; they do not add a network check or approval gate. Handle version selection, release-note content, and retirement of completed roadmaps during preparation. Preserve planned and deferred work and repair affected links when retiring roadmaps. Reuse ordinary change review for unintended files, credentials, and private data. Scope release-content review to the tagged source. ## Candidate Validation Provide one publication command that validates the final committed candidate, checks publication state, and publishes the intended refs. A validation-only mode or command may be provided for diagnosis, but must not be a required step before publication repeats the same checks. Run the complete deterministic, offline default test suite once for the final candidate, following the [testing policy](testing.md). For repositories that publish builds, verify the required build targets. Select those targets for the application's actual support commitments; native testing on each platform and access to particular hardware are not default release prerequisites. Additional gates must address a concrete risk that the existing checks do not adequately cover. Do not automatically require linting, race testing, module hygiene audits, documentation audits, credential scans, example validation, or expanded platform matrices solely because they are possible. Retain such 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, provider 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; any reuse must clearly apply to that exact candidate. Persistent validation caches are not required. If the candidate changes, validate the new candidate. Cheap publication-state checks may be repeated immediately before pushing because local or remote state may have changed during validation. Automate mechanical guards. Human review gates are strongly disfavored: add one only through an explicit project-specific policy decision explaining the concrete risk and why ordinary change review or automation is insufficient. Do not add routine confirmations for checks the command can perform itself. ## Publication Guards Automate the checks needed to publish the intended source under a fresh version: - the version has the adopted format and is unused locally and on the authoritative remote; - the worktree and index are clean on the primary release branch; - the source being published is the exact candidate that passed validation, including its matching release note; - the remote primary branch already identifies that candidate, or an atomic source/tag push will advance it to that candidate without discarding remote history; and - the tag identifies the validated candidate and only the intended refs are published. Fetch the authoritative branch and tag state as needed for these checks. Do not force branch or tag updates to bypass a failed guard. Publish explicit refs rather than all local tags. Do not require CI success, publication-service availability checks, or a separate manual confirmation for each guard. ## Immutability And Failure Recovery Published version tags and published contents are immutable. Do not move, overwrite, recreate, or delete a published tag, or replace a published artifact, checksum, signature, provenance statement, or release note under that version. The checked-in note at the immutable tag is that release's historical record. If validation fails before publication, correct and commit the candidate and rerun the publication command. If a push fails or its outcome is ambiguous, inspect the authoritative remote before retrying. Remove an unpublished local tag only after confirming it was never published or used by a release channel. An unavailable remote leaves publication status unknown; do not overwrite a tag to resolve uncertainty. Transient network, authentication, CI, or consumer-availability failures do not by themselves require a new version. Asynchronous delivery may be retried from the same immutable tag. Missing artifacts may be published later, provided existing published contents are not replaced and the additions remain consistent with the tagged source and any already-published checksum manifest. If that cannot be achieved, publish a new version. A defect requiring changes to published source or contents requires a corrected commit, a new semantically appropriate version, a matching release note, and the release procedure again. Leave the original release intact. A channel's yank, deprecation, or advisory mechanism may warn consumers away from a defective release without replacing its contents or reusing its version. ## Repository Release Procedure Maintain `docs/release.md` as a short, executable maintainer runbook. It must identify: 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; 5. the successful-push completion point and separately reported delivery status; and 6. failure handling, ambiguous-push recovery, and asynchronous delivery retries. Use copyable commands where practical. Keep optional diagnostics and consumer verification clearly optional. The procedure must not turn preparation work, ordinary change review, or post-publication investigation into additional release gates. ## Promptkit Release Configuration The release-note requirements were adopted on 2026-09-23 and licensing navigation on 2026-09-26. Apply them prospectively; previously published notes and tags retain their original records. Promptkit publishes source-only Go modules from main to origin on Gitea, using 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 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. 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 note is committed with the candidate and supplies the annotated tag message. No fixed set of section headings is required. The [publication command](../../scripts/release.sh) delegates to the released ReleaseKit tool selected in `go.mod`. The committed [profile](../../releasekit.json) selects the race-enabled Go suite, full vet, committed Go formatting, local Markdown links, workspace and filesystem replacement inspection, and the offline semantic checks for the three maintained consumer examples. These are the selected checks for the final candidate; a separate ordinary test run or standalone build is not an additional release gate. The upstream tool owns candidate, remote, and tag publication checks. It returns native status 0 for confirmed publication, 1 for a known validation or publication failure, 2 for invalid input or profile, and 3 when the push outcome is unknown. For status 3, resolve the exact captured publication endpoint before retrying; the repository-specific [procedure](../release.md#failure-recovery) links to the upstream recovery instructions. Do not wait for CI or Go module availability. Licensing footer URLs are preparation work, not a network gate.