Release Guide

Overview

Starting in 2026 we’ve modified our git workflow.

main will be the core branch where all features will get merged into and production ready code will also exist. When a release is ready to be made releases/tags will be use to point to the commit where the release should be made from.

In the past we had used dev, in conjunction with main, but there were some issues with diverging branches and new rulesets which make the main only branching strategy easier to manage.

Each release on main should be tagged properly to denote a “version” that will have the corresponding artifact on PyPI for users to pip install.

gh-pages is where official documentation will go. After each release you should build the docs and push the HTML to the pages branch. When first setting up the repo you want to make sure your gh-pages is a orphaned branch since it is disconnected and independent from the code: git checkout --orphan gh-pages.

To build the documentation, run make sphinx. To push, run make ghpages.

TLDR;

  • Each feature should have its own branch.

  • Each feature branch should be squash merged into main

  • Before a release, bump the version using bumpver.

  • Create a release from main via Releases and Tags

  • Build and push docs gh-pages. (automated via actions)

  • Build and push version to PyPI. (automated via actions)

Note

main, and gh-pages should be protected in the GitHub UI so they aren’t accidentally deleted.