Release process

cholrot uses GitHub Actions and cibuildwheel to build binary wheels for Linux, macOS, and Windows.

Supported wheel targets for the first public release are:

  • CPython 3.12, 3.13, and 3.14;

  • Linux manylinux2014 x86_64;

  • macOS x86_64 and arm64;

  • Windows AMD64.

Free-threaded CPython wheels, such as cp313t and cp314t, are deliberately not built in the first release. They should be added only after the C++ extension has been reviewed and tested for no-GIL safety.

Manual checks

Before tagging a release locally:

python -m pip install -e .[test]
pytest
CHOLROT_PURE_PYTHON=1 pytest
python -m build
python -m twine check dist/*

GitHub repository setup

After creating the GitHub repository, push the package source:

git init
git add .
git commit -m "Initial cholrot package"
git branch -M main
git remote add origin git@github.com:<owner>/cholrot.git
git push -u origin main

Replace <owner> with the actual GitHub user or organization that owns the repository.

Documentation setup

Read the Docs can be configured as soon as the GitHub repository exists. PyPI is not required for documentation hosting.

The repository contains:

  • docs/conf.py for Sphinx configuration;

  • docs/*.rst source pages;

  • .readthedocs.yaml for the Read the Docs build configuration.

To publish the documentation, import the GitHub repository in Read the Docs and let it build from .readthedocs.yaml. The generated HTML documentation can be linked from the GitHub repository and from the PyPI project description after the first package release.

Release through GitHub

  1. Update the version in pyproject.toml.

  2. Commit the change.

  3. Tag the release, for example:

    git tag v0.1.0
git push origin main --tags

  4. The wheels workflow builds the source distribution and wheels.

  5. On tag pushes, the workflow publishes to PyPI through Trusted Publishing.

PyPI Trusted Publishing

PyPI Trusted Publishing allows the release workflow to upload distributions without storing a PyPI API token in GitHub secrets. Configure a PyPI trusted publisher for the GitHub Actions workflow that publishes the release.

For a repository at github.com/<owner>/cholrot, use:

  • owner: <owner>;

  • repository: cholrot;

  • workflow name: wheels.yml;

  • environment name: pypi.

The environment name must match the environment configured in .github/workflows/wheels.yml. If the workflow environment is renamed, update the PyPI trusted publisher configuration to match.

For a first release, create a pending trusted publisher on PyPI before pushing the release tag. After the tag is pushed, GitHub Actions builds the distributions and publishes them automatically.