diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 3a025ff..387abc9 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -4,7 +4,8 @@ Material: `docs/policy/oss.md`, `docs/policy/meta.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`, -`docs/policy/architecture.md`, `docs/policy/testing.md`, `AGENTS.md`, and the +`docs/policy/architecture.md`, `docs/policy/testing.md`, +`docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section of `docs/development.md`, adapted for this repository. diff --git a/docs/policy/release.md b/docs/policy/release.md index 90f50fc..5cfb97f 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,8 +1,10 @@ # Release Policy -**Base Policy Version:** 1.2 +**Base Policy Version:** 1.4 -**Last Updated:** 2026-09-26 +**Last Updated**: 2026-09-28 + +**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md ## Purpose @@ -18,14 +20,13 @@ policy and link to it rather than introduce additional release requirements. 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`; the authoritative publication remote is -`origin`. +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. Publish `main` before -invoking the publication command; the command requires -that the remote branch exactly identifies the validated candidate and pushes -only the selected annotated tag. +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 @@ -34,19 +35,20 @@ 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. -Scriptorium publishes Linux binaries and checksums asynchronously from the -tagged source. The procedure must identify those deliverables and the +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. -Artifact delivery is a separate status. A successful tag push is not evidence -that artifacts are available. Delivery failures do not reverse source-release -success, and optional investigation must not delay release completion. +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 are not part of the adopted release channel. +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. @@ -76,9 +78,13 @@ 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. Fixed sections and -explicit no-action boilerplate are not required. Existing historical notes -need not be rewritten to adopt this format. +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 @@ -86,18 +92,11 @@ 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. -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. A release note must not substitute for current documentation. -Use annotated tags with their message derived from the checked-in note rather -than requiring a separately authored account of the same release. - -Version selection, release-note content, and retirement of completed roadmaps -are preparation responsibilities, not separate human approval gates. Preserve -planned and deferred work and repair affected links when retiring roadmaps. -Ordinary change review covers unintended files, credentials, and private data; -do not repeat it as a release-specific sign-off. Ignored local files are not -prohibited merely because they exist: they are not included in the tagged source. +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 @@ -107,24 +106,10 @@ 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), and 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. - -The selected test invocation includes the race detector because the HTTP -service shares engines and backend capacity state across concurrent requests. -This single invocation covers both ordinary assertions and race detection. -Build both declared Linux architectures with the hosted release flags to catch -cross-compilation and packaging failures; native test hardware for each target -is not required. Existing architecture tests enforce dependency boundaries. - -Retain narrow source guards against committed workspaces, vendor trees, and -module replacements: these can otherwise make a passing local build depend on -unpublished or substituted framework code. Disable workspace discovery and -vendor mode during validation. These guards preserve the established -cross-project boundary; they do not require exact dependency-version audits or -module-metadata rewrites at release time. +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 @@ -134,8 +119,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, provider probes, or inference calls. The procedure describes -dependency preparation separately from offline validation. +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; @@ -158,7 +143,9 @@ Automate the checks needed to publish the intended source under a fresh version: - 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 exact candidate; and +- 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. @@ -211,3 +198,27 @@ 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. + +## Scriptorium Release Selections + +Scriptorium publishes stable releases from `main` through the authoritative +`origin` push endpoint. The validated candidate is published to the remote +branch before the annotated version tag; the publication command requires +exact agreement between the remote branch and candidate before pushing only +that tag. Atomic branch-and-tag publication and source-only delivery remain +general alternatives in this policy, not Scriptorium-supported workflows. +The tag message derives from the checked-in note. A successful tag push +completes the source release; binary delivery is asynchronous and does not +gate it. + +The tagged source produces Linux amd64 and arm64 binaries and checksums through +the hosted workflow. Candidate validation runs the complete offline Go suite +once with the race detector because concurrent HTTP requests share engine and +backend capacity state. It builds both declared Linux targets. Narrow guards +reject committed workspaces, vendor trees, and module replacements so local +substitutions cannot mask unpublished framework code. These selected checks +address distinct application and release risks; no CI polling, artifact +availability, consumer installation, or new approval gate is required. + +The [release procedure](../release.md) owns exact commands, targets, guards, +delivery reporting, and recovery steps. diff --git a/docs/release.md b/docs/release.md index e6b6112..801c752 100644 --- a/docs/release.md +++ b/docs/release.md @@ -36,7 +36,6 @@ into the hosted release body by the existing workflow, so do not maintain a second footer there. Update affected canonical documentation with the change, and retire completed roadmap material when appropriate while preserving deferred work and links. -No extra release-specific review signoff is required. Finish and commit the intended candidate on `main`, then publish that branch: @@ -63,9 +62,8 @@ remote version, exact agreement with authoritative remote `main`, and a checked-in note whose first-level title contains Scriptorium and the exact version. Ignored local files do not make the candidate dirty. -The existing source-boundary guards reject committed workspaces, vendor trees, -and module replacements. No migration-specific exact Promptkit version audit -is required. +The source-boundary guards reject committed workspaces, vendor trees, and +module replacements. It then runs the complete suite once with the race detector and builds Linux amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 02d834e..c7745f2 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -213,7 +213,10 @@ without duplicating upstream matrices or imposing new coverage gates. ## Stage 4: Adopt Release Policy Without Changing Publication Behavior -**Status: Pending.** +**Status: Complete.** The shared release language matches the pinned source; +the local selections match the existing script, hosted workflow, and runbook. +Commands, build targets, recovery behavior, and the three-link footer remain +unchanged. Attribution now names all seven adopted policies. Files: `docs/policy/release.md`, `docs/release.md`, attribution entry.