Release Process

Alpha releases are maintainer-gated. Ordinary pushes and pull requests must not publish packages.

Release Checklist

Before publishing an alpha:

  • confirm the roadmap and changelog describe the release scope;

  • confirm all public examples are synthetic or explicitly public-safe;

  • confirm private PDFs, crops, overlays, review manifests, prompt logs, and recovered private tables are not tracked;

  • confirm the version in pyproject.toml matches the intended release;

  • run the local release checks;

  • run the release workflow with skip-publish enabled;

  • publish to TestPyPI first when credentials or trusted publishing are ready;

  • publish to PyPI only after maintainer approval.

Local Release Checks

rm -rf dist build
python -m ruff check .
python -m pytest
sphinx-build -b html docs _build/html -W
python -m build
twine check dist/*

Clean Wheel Install

For release candidates, verify the built wheel in a fresh environment:

python -m venv tmp/release-check-venv
. tmp/release-check-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install dist/figrecover-*.whl
figrecover --help
deactivate

GitHub Release Workflow

The release workflow is manually triggered with two controls:

  • target selects testpypi or pypi;

  • skip-publish defaults to true and performs build verification without publishing.

Publishing jobs use GitHub environments named testpypi and pypi so the repository can require maintainer approval and trusted-publishing configuration before upload.

Trusted Publishing Setup

TestPyPI and PyPI each need a trusted publisher entry before the release workflow can upload packages without an API token.

Use these claims:

  • repository owner: UBC-FRESH;

  • repository name: figrecover;

  • workflow filename: release.yml;

  • TestPyPI environment: testpypi;

  • PyPI environment: pypi.

The first alpha was published successfully after these publishers were configured. The TestPyPI subject claim used during setup was:

repo:UBC-FRESH/figrecover:environment:testpypi

Version Policy

The Phase 8 alpha target is 0.1.0a1. Later alpha releases should increment the alpha suffix. Stable 1.0.0 release work is reserved for Phase 9 publication and peer-review readiness.

v1.0.0 Release Candidate And Archive

The stable 1.0.0 release must be handled as a reviewed release, not as a routine alpha increment. Phase 9 keeps the detailed release-candidate and archive plan in planning/v1-release-archive-plan.md until the package is ready to cut a release candidate.

The first release candidate should not be tagged until the v1.0.0 readiness gaps are closed or explicitly deferred, public APIs and deprecation policy are documented, examples are confirmed public-safe, release checks pass, and the archive/DOI path is configured. The final v1.0.0 release should be published only after release-candidate validation and maintainer approval.

No private PDFs, generated private crops, recovered private tables, prompt logs, or unapproved case-study artifacts may be included in release archives.