Skip to content

Creating A Release

This guide covers the op_engine release process for this repository's two Python distributions:

  • op_engine
  • flepimop2-op_engine

The release workflow treats them as a single release unit. Both package versions must match, and the workflow publishes them sequentially under one GitHub release tag.

Prerequisites

  • You have write access to the ACCIDDA/op_engine repository.
  • The release version has already been updated everywhere it is declared:
  • pyproject.toml
  • flepimop2-op_engine/pyproject.toml
  • Your local environment is synced with a supported complete Python version.
  • CITATION.cff version, release date and artifact URL match the shared release; attribution and applicable grants have been reviewed.
  • You have GitHub's gh CLI installed and authenticated if you plan to dispatch workflows from the command line.

1. Confirm The Shared Version

The release workflow validates that all version declarations match before it builds or publishes anything.

Today that means these two files must contain the same semantic version:

  • pyproject.toml
  • flepimop2-op_engine/pyproject.toml

If any of them differ, the validate job fails immediately.

The workflow also validates that flepimop2-op_engine depends on the exact matching op-engine release version. For example, release 0.2.0 must declare op-engine==0.2.0.

2. Run The Local Release Preflight

Use the local pre-release target before dispatching the release workflow:

just release-validate

That command validates citation syntax and shared metadata, then:

  • Validates that the release version matches in:
  • pyproject.toml
  • flepimop2-op_engine/pyproject.toml
  • Runs just build-all to execute the clean-room build and install tests for both packages.

The release workflow runs the same validation again on GitHub Actions before publishing.

3. Run The Release Workflow

Releases are created through the manual GitHub Actions workflow in .github/workflows/release.yaml.

If you are testing the workflow before merging, add --ref <branch-name> to the gh workflow run command. Without --ref, GitHub dispatches the workflow definition from the repository's default branch.

Dry Run

Use this to validate shared versioning, build both packages, and upload release artifacts without publishing anything:

gh workflow run release.yaml \
  --repo ACCIDDA/op_engine \
  --ref <branch-name> \
  --field publish-target=none \
  --field create-github-release=false \
  --field deploy-docs=false

This runs the validate, publish-core, and publish-provider jobs, but the publish jobs become no-ops when publish-target=none.

TestPyPI

Use this to publish both packages to TestPyPI without creating the GitHub release or deploying docs:

gh workflow run release.yaml \
  --repo ACCIDDA/op_engine \
  --ref <branch-name> \
  --field publish-target=testpypi \
  --field create-github-release=false \
  --field deploy-docs=false

The workflow always publishes in dependency order:

  1. op_engine
  2. flepimop2-op_engine

When testing from a branch, keep create-github-release=false and deploy-docs=false. The reusable docs workflow checks out main, so it is not intended for pre-merge branch testing.

PyPI

Use this to publish both packages, create a GitHub release, and deploy the versioned documentation:

gh workflow run release.yaml \
  --repo ACCIDDA/op_engine \
  --field publish-target=pypi \
  --field create-github-release=true \
  --field deploy-docs=true

When create-github-release=true, the workflow creates a single vX.Y.Z GitHub release for the shared package version and uses GitHub's generated release notes.

4. Documentation Deployment

The release workflow calls .github/workflows/gh-pages.yaml as a reusable workflow when deploy-docs=true.

That workflow supports two deployment modes:

  • push: for normal main branch documentation updates
  • release: for a tagged release, which updates the release alias in mike

If you want to deploy docs manually without running a release, you can dispatch gh-pages.yaml directly and choose the deploy mode in the GitHub Actions UI.

5. Trusted Publishing Setup

The publish jobs use PyPI Trusted Publishing rather than a stored API token.

For publish-target=testpypi, configure the TestPyPI trusted publisher entry for:

  • Owner: ACCIDDA
  • Repository: op_engine
  • Workflow file: release.yaml

For publish-target=pypi, configure the PyPI trusted publisher entry for the same repository and workflow file.

Because this repository publishes two distributions from one workflow, the same trusted publisher setup must be allowed to publish both package names on the selected index.

6. Package Metadata

Published package metadata must use registry-compatible dependencies. The provider package must not declare direct URL dependencies, because PyPI rejects distributions that require them.

Required CPU qualification is a separate release gate: run just qualify and retain the NumPy/JAX/CPU Torch logs alongside baseline checks. Document GPU execution as unqualified unless explicit hardware checks have executed without skips. See the capability matrix.

The citation/archive guide records the ACCIDDA Zenodo follow-up. Complete readiness evidence before freezing a software-paper release, then record its verified version DOI after the deposit resolves.