Skip to content

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:

  1. Set LESSON_RELEASE in tools/build_fundamental_tutorials.py to the new version. The three lesson generators and their requirement files take it from there, and tests/docs/test_coverage_tutorials.py fails while it differs from the version that the installation guide installs.
  2. Install the candidate wheel and the pinned lesson dependencies into a new, non-editable environment, without PYTHONPATH.
  3. Run each generator with --write (with a new --work-dir where it asks for one), as fundamental, study and coverage tutorial maintenance describe, and then with --check.
  4. 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.