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.1.0, dated 2026-10-23. The published v1.0.0, v1.0.1 and v1.0.2 tags and distributions remain immutable. Keep the historical 1.0.0 compatibility fixtures and artifact schemas unchanged. See the 1.1.0 release notes for the included changes.

Update the runtime version, citation, changelog, release notes, version consistency test, and exact candidate and publication workflow versions in one reviewed commit. 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.1.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.1.0 tag. If deployment restrictions still allow only earlier tags, an authorized maintainer must add v1.1.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.

Organization Pages

In the organization repository, open Settings > Pages > Build and deployment and set Source to GitHub Actions. The guarded docs.yml workflow builds the documentation portal strictly and deploys documentation only to https://vamos-optimization.github.io/VAMOS/. It runs on the official tag or a manual workflow dispatch. The generated portal mirrors the canonical .org layout: the current documentation is built at clean root paths, immutable release documentation lives under docs/<version>/. Compatibility trees under docs/stable/, latest/, and root-level <version>/ contain redirects rather than a second canonical documentation surface. The personal mirror must not deploy canonical Pages. Confirm the deployment and canonical .org metadata during the final release Goal.

tools/build_release_docs.py --version 1.1.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 input 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.1.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.1.0 \
  --expected-branch release/final-1.1.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.1.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.1.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.