Release workflow

  1. Change the version number in __about__.py

  2. Commit changes with a message like release: bump version to X.x.x to the main branch

  3. Apply a git tag with the relevant version: git tag -a 0.3.0 {git commit hash} -m "New awesome feature"

  4. Push commit and tag to main branch: git push --tags

Pushing the tag triggers the builder_releaser.yml workflow. It builds the executables and the Python package (source and wheel distributions), creates the GitHub release with all of them attached, then publishes the Python package to PyPI.

Before building, the workflow runs twine check --strict on the distributions and checks that the tag matches the version declared in __about__.py (compared as PEP 440 versions: 4.0.0-beta9 and 4.0.0b9 are the same version).

On a pull request touching pyproject.toml, MANIFEST.in or the workflow itself, the Python package is built and checked without publishing anything.

PyPI publication

The publication relies on PyPI Trusted Publishing (OpenID Connect): no API token is stored in the repository.

One-time setup, before the first release:

  1. On PyPI, in the account’s publishing settings, add a pending publisher with the project name dicogis, the owner Guts, the repository DicoGIS, the workflow builder_releaser.yml and the environment pypi

  2. On GitHub, in the repository settings, create an environment named pypi (optionally with required reviewers, to confirm each publication)

The first successful publication turns the pending publisher into a regular one.

A version can be published only once on PyPI: even deleted, a file can’t be uploaded again under the same name, so moving the tag and re-running the workflow doesn’t fix a faulty release. Yank it and publish a new version.

Unpublish a tag

git tag -d old
git push origin :refs/tags/old
git push --tags

Manual upload to PyPi

This method requires an API token on PyPi

If the CI/CD fails for any reason, here comes the manual procedure:

  1. Install required packages:

    python -m pip install -U build twine
    
  2. Clean previous builds and build package artifacts (source and wheel distributions, in dist/):

    rm -rf dist/
    python -m build
    
  3. Check built artifacts:

    twine check --strict dist/*
    
  4. Upload built artifacts to PyPi:

    twine upload -u __token__ dist/*