Release process
Releases are cut from main by pushing a version tag. The Release workflow
(.github/workflows/release.yml) does the rest. No maintainer builds or uploads artifacts by hand.
What the workflow guarantees
| Step | Guarantee |
|---|---|
| Version check | The tag equals v + the version in pyproject.toml, decision_forge.__version__, and CITATION.cff, and CHANGELOG.md has a non-empty section for it |
| Tests | The full test suite passes on the tagged commit |
| Build | The sdist and wheel are built with uv build and pass twine check --strict |
| Smoke test | The wheel installs into a clean environment, reports the tagged version, and validates the example project |
| Provenance | Each artifact receives a GitHub build provenance attestation signed through Sigstore |
| GitHub release | A release named after the tag carries the artifacts and the matching changelog section; PEP 440 pre-releases (a, b, rc) are marked as pre-releases |
| PyPI (opt-in) | Artifacts are uploaded through PyPI trusted publishing without long-lived tokens |
scripts/check_release.py runs without a tag in the test suite, so version drift between the package,
citation, and changelog fails ordinary pull request CI as well.
Cutting a release
- Open a pull request that:
- sets the new version in
pyproject.toml,src/decision_forge/__init__.py, andCITATION.cff; - renames
## UnreleasedinCHANGELOG.mdto## X.Y.Zand adds an empty## Unreleasedabove it; - updates version references in
README.md,README.zh-CN.md, andSECURITY.md. - Run
uv lockso the lock file records the new project version, then merge after CI passes. - Tag the merge commit and push the tag:
bash
git switch main && git pull --ff-only
uv run python scripts/check_release.py --tag vX.Y.Z
git tag -a vX.Y.Z -m "Decision Forge vX.Y.Z"
git push origin vX.Y.Z
- Watch the Release workflow. If a step fails, fix the cause on
main, delete the tag locally and remotely, and tag again. Never move a tag after a release has been published.
Verifying a release
Anyone can confirm that an artifact was built by this repository's release workflow:
gh release download vX.Y.Z --repo Juneo-Lab/decision-forge --pattern '*.whl'
gh attestation verify decision_forge-X.Y.Z-py3-none-any.whl --repo Juneo-Lab/decision-forge
One-time PyPI setup
PyPI publishing stays disabled until a maintainer opts in:
- On PyPI, add a trusted publisher for the
decision-forgeproject with ownerJuneo-Lab, repositorydecision-forge, workflowrelease.yml, and environmentpypi. - In Settings → Environments, create the
pypienvironment and restrict it tov*tags. Add required reviewers if releases should need a second approval. - Set the Actions repository variable
PUBLISH_PYPItotrue.
Versioning
Decision Forge follows Semantic Versioning with PEP 440 pre-release suffixes. Before 1.0, minor versions may change export formats, engine fingerprints, and CLI behavior; the changelog states when existing run directories must be rebuilt. Export formats are versioned independently of the package.