Releasing

This document describes how to make a new release of planegcs.

Overview

Releases are built using cibuildwheel in GitHub Actions and published to PyPI. The workflow is triggered manually from the GitHub Actions UI.

What gets built:

  • Platforms: Linux (manylinux, x86_64) and Windows (x86_64)

  • Python versions: 3.12 and 3.13

  • Artifacts: platform wheels + source distribution (sdist)

Step-by-step release process

The release.sh script automates the local steps (version bump, commit, tag, push). Run it from the repository root:

./release.sh <version>

where <version> is the argument passed to uv version.

We roughly follow Semantic Versioning:

  • MAJOR — incompatible API changes

  • MINOR — new functionality, backwards-compatible

  • PATCH — backwards-compatible bug fixes

The script will:

  1. Check that the working tree is clean and you are on main.

  2. Bump the version in pyproject.toml.

  3. Commit the change and push to origin main.

  4. Create a vX.Y.Z tag and push it.

  5. Open the GitHub Actions workflow page (or print the URL) so you can trigger the build.

Triggering the release workflow

After the script finishes, trigger the build on GitHub Actions:

  1. Go to https://github.com/spookylukey/planegcs/actions/workflows/release.yml (the script will try to open this for you).

  2. Click Run workflow.

  3. Choose the main branch.

  4. Click Run workflow.

The workflow will:

  • Build wheels for Linux and Windows.

  • Build a source distribution.

  • Run the test suite against each wheel.

  • If upload_to_pypi was true, publish everything to PyPI.

PyPI authentication

The publish step uses PyPI trusted publishing (OpenID Connect). This requires one-time setup on PyPI:

  1. Go to https://pypi.org/manage/project/planegcs/settings/publishing/

  2. Add a new GitHub trusted publisher:

    • Owner: <your GitHub username> (or your GitHub org/username)

    • Repository: planegcs

    • Workflow name: release.yml

    • Environment name: pypi

Once configured, the workflow can publish without any API tokens or passwords.

Note

If you prefer to use a PyPI API token instead of trusted publishing, store the token as a GitHub Actions secret named PYPI_API_TOKEN and replace the publish step in .github/workflows/release.yml with:

- name: Publish to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    password: ${{ secrets.PYPI_API_TOKEN }}

Troubleshooting

Wheels fail to build on Windows

Check that vcpkg can install the dependencies. The GitHub Actions windows-latest runner has vcpkg pre-installed. The workflow runs vcpkg install eigen3:x64-windows boost-graph:x64-windows boost-math:x64-windows before building.

Wheels fail to build on Linux

The manylinux container uses yum. The before-all command tries yum first, then falls back to apt-get.

Tests fail in cibuildwheel

cibuildwheel installs the built wheel into a fresh virtualenv and runs pytest {project}/tests -x. Check the test output in the workflow logs.

Version mismatch

The version lives in pyproject.toml. The release.sh script uses uv version --bump to update it automatically.

File reference

  • release.sh — automates version bump, commit, tag, and push

  • .github/workflows/release.yml — the release workflow

  • .github/workflows/ci.yml — CI workflow (runs tests on push/PR)

  • pyproject.toml — build config including [tool.cibuildwheel] settings

  • CMakeLists.txt — CMake build (cross-platform, supports MSVC and GCC/Clang)