Release verification¶
Canonical repository and publisher identity¶
Release work originates from vamos-optimization/VAMOS.
The repository governance policy defines the
personal mirror and the one-way synchronization of canonical history.
Only the organization repository may recover publication input, request OIDC
publishing credentials, or create official releases. The upload_pypi.yml
repository guard rejects mirrors and forks before artifact recovery; every
subsequent publication job depends on that guard.
Preparing the next release¶
The current candidate is 1.5.0, dated 2026-11-19. The published
v1.0.0, v1.0.1, v1.0.2, v1.1.0, v1.2.0, v1.2.1, v1.3.0 and v1.4.0 tags and distributions remain immutable. Keep the
historical 1.0.0 compatibility fixtures and artifact schemas unchanged.
See the 1.5.0 release notes for the included changes.
Update the runtime version, citation, changelog, release notes (with their entry
under Reference → Support & Versions in mkdocs.yml), version consistency test,
and exact candidate and publication workflow versions in one reviewed commit.
Build the changelog from the "Changelog entry" sections of the pull requests
merged since the previous release; those pull requests do not edit
CHANGELOG.md. Freeze the final merged organization main commit; if that
commit changes, produce new evidence before publishing. Verify the actual
publication date before freezing.
Run full local and hosted release validation. The candidate workflow accepts
release/final-1.5.0 pull requests and manual dispatch. After merging, dispatch
release.yml on the final main commit and wait for all source and installed
wheel gates, including the frozen-evidence job, to succeed. The pre-release tag
check requires the new tag to be absent and all previous public annotated tags
to match their remote objects and remain ancestors of the candidate.
Trusted Publisher identities remain:
| Registry | Project | Owner | Repository | Workflow | Environment |
|---|---|---|---|---|---|
| TestPyPI | vamos-optimization | vamos-optimization | VAMOS | upload_pypi.yml | testpypi |
| PyPI | vamos-optimization | vamos-optimization | VAMOS | upload_pypi.yml | pypi |
Confirm both existing publisher registrations and the GitHub environments
before creating the annotated v1.5.0 tag. If deployment restrictions still
allow only earlier tags, an authorized maintainer must add v1.5.0 while preserving
production approval requirements. Use OIDC; do not introduce API tokens or
publish through a mirror. A required deployment approval must be completed
through the normal environment approval flow.
Keep private vulnerability reporting enabled in the canonical repository's security settings. The repository governance policy continues to govern synchronization of the personal mirror after publication.
Push the annotated tag at the validated final source commit. Publication recovers the exact successful freeze, uploads the same bytes to TestPyPI, checks installation and hashes, then publishes to PyPI and creates the GitHub Release. Verify the production package, hashes, and release before declaring completion. Never replace an existing version or move a published tag.
Regenerate the lessons¶
The fundamental, study and coverage lessons, including the algorithm guides with recorded output, show what the release they name prints. Every release regenerates them on its release branch with a wheel built from that branch, before the release pull request merges. The wheel contains neither the lessons nor their sources, so the regeneration commit leaves the distributions unchanged:
- Set
LESSON_RELEASEintools/build_fundamental_tutorials.pyto the new version. The three lesson generators and their requirement files take it from there, andtests/docs/test_coverage_tutorials.pyfails while it differs from the version that the installation guide installs. - Install the candidate wheel and the pinned lesson dependencies into a new,
non-editable environment, without
PYTHONPATH. - Run each generator with
--write(with a new--work-dirwhere it asks for one), as fundamental, study and coverage tutorial maintenance describe, and then with--check. - Compare each changed output with the text of its page, update the prose that cites the old numbers, and name the corrections that changed them in the release pull request.
Organization Pages¶
In the organization repository, open Settings > Pages > Build and deployment
and set Source to GitHub Actions. The guarded docs.yml workflow deploys
https://vamos-optimization.github.io/VAMOS/ as a redirect to
https://vamos-optimization.org/; it builds no documentation and does not run
on tags, so a release does not redeploy it. Dispatch it manually from main
only when the redirect changes. The personal mirror must not deploy Pages. The
documentation delivery guide
describes the redirect. Documentation is published through the Cloudflare
production workflow, which attaches the portal archive to the GitHub Release.
tools/build_release_docs.py --version 1.5.0 --output <new-directory> builds
the complete deployment layout. It builds the current documentation and the
immutable release separately so each has the correct canonical URL, preserves
previous immutable docs/<version>/ trees when an archive directory or portal
archive is supplied, generates the compatibility redirects, and refuses an
existing output directory. The documentation smoke tests verify that every
emitted canonical URL resolves to a file in that deployment layout.
Canonical validation¶
tools/release_check.py is the canonical, fail-closed VAMOS release gate. It
validates the source tree, stable contracts, typing policy, full test suite,
both documentation sites, distributions, installed wheel, dependencies, and
release evidence in one command:
python tools/release_check.py --version 1.5.0
Run it from a clean release branch with the development, documentation, compute, and release tooling installed. Keep a second dependency-minimal environment for the canonical typing and health gates; optional compute, analysis, and Studio distributions intentionally do not enter that environment. Build and release tools are pinned and audited separately from runtime dependencies:
python -m pip install -c constraints/ci.txt -e ".[dev,docs,compute,analysis,examples,studio]"
python -m pip install -r release/requirements-build.txt
python -m pip install -r release/requirements-tools.txt
python -m venv <typing-venv>
<typing-venv>/bin/python -m pip install -r release/requirements-build.txt
<typing-venv>/bin/python -m pip install --no-build-isolation -c constraints/ci.txt -e ".[dev]"
For an auditable candidate, bind the check to the intended identity and write evidence outside the repository:
python tools/release_check.py \
--version 1.5.0 \
--expected-branch release/final-1.5.0 \
--expected-commit <full-commit-sha> \
--tag-state pre-release \
--typing-python <typing-venv>/bin/python \
--output-dir <new-empty-evidence-directory>
Use --json when a machine consumer requires exactly one JSON document on
standard output. --list-checks exposes the ordered check inventory. Evidence
directories are append-never: the checker refuses to overwrite a non-empty
directory.
Frozen distributions¶
The compatibility gate runs all tests under tests/compatibility/, including
the permanent structural snapshots and the 1.0.0 run/study artifact corpus.
Those checks load, verify, inspect, and summarize the committed canonical bytes
and compare public study JSON command results without regenerating fixtures.
Fixture maintenance is documented in tests/compatibility/v1_0_0/README.md.
The candidate workflow builds one wheel and one sdist exactly once. Every downstream platform downloads those same bytes. When validating an existing candidate, pass its directory instead of rebuilding it:
python tools/release_check.py \
--version 1.5.0 \
--artifacts <directory-with-one-wheel-and-one-sdist> \
--output-dir <new-empty-evidence-directory>
The evidence contains SHA-256 checksums, a CycloneDX SBOM, the installed runtime lock, dependency-audit reports, artifact metadata/content inspection, and provenance tied to the source commit. Publication consumes the frozen workflow artifact and verifies every byte again; it never rebuilds from the tag.
Installed-wheel smoke¶
tools/release_smoke.py is designed to run from a clean, non-editable wheel
environment with no repository import path. Its full mode exercises public
imports, optimization, byte-exact replay, durable study execution, controlled
failure/resume/retry, relocation, and human and JSON CLI contracts while
blocking network access.
The release checker clears the checkout's PYTHONPATH for wheel installation,
dependency inventory, and smoke execution. This prevents source-tree metadata
from making pip treat an uninstalled wheel as already installed. Run the full
smoke with:
python tools/release_smoke.py --version 1.5.0 --mode full
--mode core omits the optional-backend failure scenario and is used by the
minimal and non-primary platform jobs. The hosted matrix covers Linux, Windows,
and macOS; minimum Python, primary Python, and the declared maximum tested
Python; a minimal wheel and the supported optional dependency set.
Gate policy¶
Strict and stable typing must be clean. Full-source typing must match its exact
no-regression baseline; full-zero remains informational for VAMOS 1.0.0 and
does not claim that inherited typing debt is resolved. Runtime dependency
findings block the release. Build and release-tool audits are recorded
separately and surface findings as warnings for owner review; the pinned 1.0.0
tool sets are expected to audit clean.
Ruff lint is clean across production, tests, and release tools. Ruff formatting uses the repository's explicit ratcheted formatting budget, so this release does not disguise inherited formatting debt as global formatter compliance.
Use --tag-state pre-release for an update candidate. It preserves and
verifies previous published tags while rejecting an already existing candidate
tag. The first-release normalization states remain available only for their
historical checks. Do not publish if repository identity, artifact hashes,
TestPyPI installation, or any critical gate differs from the frozen candidate.
TestPyPI is published first using trusted publishing. Only after its exact wheel installs and passes the full smoke may the same immutable wheel and sdist be sent to PyPI and attached to the GitHub release with their checksums, SBOM, manifest, provenance, stability contract, and known limitations.
VAMOS 1.3.0: the GitHub release's text is the version's release
notes with absolute links, written by tools/github_release_notes.py: links to
documentation pages point to the version's archive,
https://vamos-optimization.org/docs/<version>/, and links to other files to
the version's tag on GitHub. The notes' relative links broke on the release
page. To correct an earlier release, run the tool on that tag's notes and pass
the output to gh release edit v<version> --notes-file.