Skip to content

Preparing a release

Jump to bottom
Estefania Barreto-Ojeda edited this page Jun 17, 2026 · 2 revisions

Release management

Versioning

  • We use semantic versioning MAJOR.MINOR.PATCH (i.e., briefly, major revision changes whenever the API changes in backwards-incompatible manner, MINOR changes for new features, PATCH changes for fixes that correct functionality; as long as MAJOR == 0, we can break the API with increasing MINOR.)

  • Releases are cut from the main branch and tagged with MAJOR.MINOR.PATCH (note: the release tag comes from git tags, which are configured in the pyproject.toml via versioningit)

Before a new release

  • Make sure all changes for the release are merged into main and all the CI passes.
  • Check the CHANGELOG.rst is up to date and it includes all the changes with new version and release date.
  • Decide the new version number (MAJOR.MINOR.PATCH).

Release process

Releases are handled by the deploy.yaml workflow. With this workflow, the deployment is reduced to two steps:

  • Step 1: Push the version tag and trigger the deployment workflow. From an up-to-date main branch with the new version number (MAJOR.MINOR.PATCH), push the version tag and trigger the deployment workflow:

    git checkout main
git pull origin main
git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch>"
git push origin v<major>.<minor>.<patch>

    The package will be built and published to TestPyPI. The workflow will also run the tests and verify the package can be installed from TestPyPI.

    ⚠️ Wait for the deployment workflow to complete and the package to be published to TestPyPI. Don't proceed with step 2 until the workflow passes with no errors and the package is available on TestPyPI.

  • Step 2: Publish a GitHub Release. Once the package is published to TestPyPI, go to GitHub → Releases → Draft a new release, select the tag you pushed in Step 1, add release notes from CHANGELOG.rst. Click on Publish release to publish the release.

Publishing the GitHub Release triggers the deployment workflow again, this time to upload the package to PyPI. The workflow will run tests and verify the package can be installed from PyPI.

Outcome

  • The package is published to TestPyPI after a new tag is pushed (step 1).
  • When a GitHub Release is published, the package is published to PyPI (step 2).
  • The documentation is automatically updated and published to ReadTheDocs.

Note that a separate process is used to release the conda package. See conda-forge/membrane-curvature-feedstock for more details.

Future enhancements

  • Zenodo archival
  • conda release

Clone this wiki locally