Creating and Uploading Releases to PyPI

This guide describes how PMMoTo releases are built and published to PyPI using the GitHub Actions workflow Build and Release. Releases are fully automated and triggered by pushing a version tag to the repository.

Prerequisites

Before creating a release, ensure:

  • You have push access to the PMMoTo GitHub repository.

  • The PYPI_API_TOKEN secret is configured in the GitHub repository settings.

  • The package version has been updated according to semantic versioning.

Versioning

PMMoTo follows Semantic Versioning:

  • Major version: incompatible API changes

  • Minor version: backward-compatible feature additions

  • Patch version: backward-compatible bug fixes

Example version:

1.2.3

  • 1 → major version

  • 2 → minor version

  • 3 → patch version

Git tags must be prefixed with v:

v1.2.3

Updating the Version

Before tagging a release, update the version number in pyproject.toml

Commit the version change to the main branch:

git add pyproject.toml
git commit -m "Bump version to 1.2.3"
git push

Creating a Release

Releases are triggered by pushing a version tag:

git tag v1.2.3
git push origin v1.2.3

This will automatically start the Build and Release GitHub Actions workflow.

What the Workflow Does

The GitHub Actions workflow performs the following steps:

  1. Build wheels using cibuildwheel on: - Ubuntu - macOS (Intel) - macOS (Apple Silicon)

  2. Build a source distribution (sdist) on Linux.

  3. Upload all artifacts to PyPI using the official PyPA publish action.

No manual steps are required after pushing the tag.

Workflow Trigger

The workflow is triggered by version tags matching:

on:
  push:
    tags:
      - "v*.*.*"

Publishing to PyPI

Publishing is handled automatically using:

  • pypa/cibuildwheel for wheels

  • python -m build for the sdist

  • pypa/gh-action-pypi-publish for uploading

Authentication is done using the PYPI_API_TOKEN GitHub secret.

Verifying the Release

After the workflow completes successfully, verify the release at:

https://pypi.org/project/pmmoto/

You can also inspect the workflow logs in GitHub Actions to confirm that wheels and the source distribution were uploaded correctly.

Notes

  • Do not upload releases manually using twine.

  • All official releases should be created via Git tags.

  • If a release fails, fix the issue, bump the version, and create a new tag.