release

name	release
description	Cut an osr-editor release — version bump, changelog discipline, the annotated tag that drives release.yml, the local dry run before tagging, and recovery when a release fails. Use when cutting a release, bumping the version, or working on release.yml.

Releasing osr-editor

• The version lives in pyproject.toml alone; _editor_version() reads installed metadata at runtime and no __version__ symbol exists (osrlib rejected one explicitly, and this repo inherits the rationale). The bump procedure: edit the version, run uv lock, and nothing else.
• Changelog discipline applies from the first phase: a PR that changes user-visible behavior adds its bullet to the [Unreleased] section of CHANGELOG.md in the same PR. Cutting a release renames [Unreleased] to [X.Y.Z] - <date>, leaves an empty [Unreleased] above it, and updates the link-reference block at the bottom of the file ([Unreleased] comparing vX.Y.Z...HEAD, each version pointing at its release tag). Maintaining that block is part of every release cut — osrlib's own block drifted unmaintained after 1.3.0, and this repo does not repeat that.
• A release is an annotated vX.Y.Z tag on the merge commit (git tag -a vX.Y.Z -m "osr-editor X.Y.Z", then push the tag). release.yml does the rest: fails fast if the tag doesn't match the pyproject version, re-runs the standing gate's four artifact-proving jobs (backend, frontend, types, e2e, duplicated by hand — a tag push triggers no CI run; ci.yml's fifth job, screenshots, is deliberately not among them — the release gate exists to prove the shipped wheel, and the strict docs build below already fails if any referenced screenshot is missing from the tagged tree) plus the strict docs build, builds once — the Vite build before uv build, the ordering that puts the frontend in the wheel — audits the artifacts with scripts/release/check_dist.py, smoke-tests the wheel in a fresh venv on both OSes with scripts/release/install_smoke.py (which boots the installed console script and fetches the UI from it), publishes to PyPI via trusted publishing (no tokens anywhere in the repository), and creates the GitHub Release from the tagged version's changelog section.
• The local dry run before tagging starts with the frontend build — a dry run that skips it audits a stale static tree: cd frontend && npm ci && npm run build && cd .., then uv build, then python3 scripts/release/check_dist.py dist X.Y.Z, then install the wheel into a fresh venv (uv venv --python 3.14 smoke-venv, uv pip install --python smoke-venv/bin/python dist/osr_editor-*.whl) and run smoke-venv/bin/python scripts/release/install_smoke.py X.Y.Z.
• Recovery: any failure before the publish job leaves PyPI untouched — delete the tag, fix on a branch, re-tag. Once publish succeeds, that version's filenames are burned on PyPI and the next attempt is a new version. The docs gate fetches the siblings' objects.inv inventories over HTTP at build time — the one named build-time network dependency — so an upstream outage fails the gate before publish, and the same recovery rule covers it.
• One-time setup, completed during the 0.1.0 release (2026-07-24): the PyPI pending trusted publisher for project osr-editor (repository mmacy/osr-editor, workflow release.yml, environment pypi), the matching pypi environment in the GitHub repo, and the Pages source set to "GitHub Actions". Provenance, recorded honestly the first time: a pending publisher existed before the release naming workflow package_pub.yml with no environment constraint; it was replaced during the release with the release.yml/pypi publisher the workflow actually authenticates as.
• Versioned documentation is not adopted; Pages-from-main is the whole deployment. The adoption trigger, carried from the siblings verbatim: the first post-1.0 release whose published docs must describe behavior different from main adopts mike or equivalent in that release's own plan. Patch and docs-only releases do not trigger it.