Releases and versions

Each release of uncertaintylib is a git tag MAJOR.MINOR.PATCH without a prefix, for example 1.2.0, the sdist and the wheel on PyPI, and a GitHub release with notes and the same two files attached.

Version numbers

Versions follow semantic versioning:

Part

Increased for

Example

PATCH

a fix that does not change the documented behaviour or any calculated result

1.2.0 → 1.2.1

MINOR

new functionality that existing code keeps working with

1.2.0 → 1.3.0

MAJOR

a change that breaks existing code or the documented behaviour

1.2.0 → 2.0.0

Project rule: a change to calculated results - for example a corrected formula, a changed default, constant or uncertainty model - is at least MINOR, even when it is a correction, so it never arrives unnoticed in a patch update. Describe the effect on results in the pull request; the release notes are generated from the pull request titles.

No file in the repository holds the version. setuptools-scm reads it from the git tag when the package is built or installed and writes it to uncertaintylib/_version.py (not committed), and uncertaintylib.__version__ reports it:

Where the package came from

__version__

PyPI, tag 1.2.0 or its sdist/wheel

1.2.0

a commit after 1.2.0

a development version such as 1.2.1.dev3+g1a2b3c4

a source tree without an install

0+unknown

Building from a git checkout needs the tags (a full clone, or fetch-depth: 0 in a workflow). An editable install (pip install -e .) records the version when it is installed; after pulling new commits or tags, run pip install -e . again to update it. tests/test_version.py fails until you do.

Making a release

A release is always started by a person; merging or pushing to main never releases anything.

  1. Make sure every change meant for the release is merged into main.

  2. On GitHub, open Actions → Release → Run workflow, keep the branch main, and choose which part of the version to increase (patch, minor or major). The workflow works out the new version from the highest existing release tag.

  3. The workflow, .github/workflows/release.yml, runs on the commit main pointed at when it was started:

    1. prepare - stops unless the run is on main, works out the version (tools/release_version.py) and stops if the tag or the version on PyPI already exists.

    2. test - the full test workflow, tests.yml.

    3. build - tags the commit locally (not pushed) so setuptools-scm gives the release version, builds the sdist and the wheel once, checks their names, content and metadata (twine check --strict), installs each into a clean virtual environment and runs the test suite against it, and keeps exactly those files with their SHA-256 sums.

    4. publish - waits for approval in the environment pypi, checks the files against the SHA-256 sums, checks what PyPI already holds for the version, creates the tag at the release commit, uploads the files to PyPI with Trusted Publishing (no PyPI token is stored anywhere) and checks that PyPI holds exactly those files.

    5. github-release - creates the GitHub release for the tag, with generated notes and the same files attached.

  4. Edit the release notes on GitHub if the effect on calculated results needs explaining.

A release needs one approval, in the environment pypi. Nothing is tagged or published before it.

If a release run fails

  • Before the publish job has started, nothing is tagged or published: fix the cause and start a new run.

  • Once the publish job has started, use Re-run failed jobs in the same run. The publish job accepts its own earlier partial work only on a re-run of the same run (same commit, same files): an existing tag must point at the release commit, and files already on PyPI must be the ones built in that run (same SHA-256, with PyPI provenance from this repository’s release.yml in the environment pypi). Do not use Re-run all jobs: the prepare job refuses to run in a later attempt, as it would work out the next version from tags that may include the one this run created.

  • Never start a new run for a version that already has files on PyPI, and never upload by hand. PyPI never accepts a file name twice, even after deletion.

  • A published tag is never moved or deleted. A mistake is corrected by a new release.

One-time setup

Settings made once by a repository administrator, before the first release:

  • Environment - Settings → Environments: create pypi with Required reviewers and, under Deployment branches and tags, only the branch main. Its approval is the only approval of a release.

  • Trusted Publisher on PyPI - on pypi.org, uncertaintylib → Manage → Publishing: add a GitHub trusted publisher with owner equinor, repository uncertaintylib, workflow release.yml and environment pypi.

  • Protect release tags (optional) - Settings → Rules → Rulesets → New tag ruleset, target refs/tags/[0-9]*, with Restrict updates and Restrict deletions. Do not restrict creation, as the workflow creates the tag.