eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

Align release policy with existing publication workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:44:38 +00:00
parent b3bb36fc86
commit 417522f08c
4 changed files with 69 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/policy/release.md
View File

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