Releasing a new version#

Most of the process related to releasing a new version of cotainr is automated. However a few things, as detailed on this page, must still be done to initiate the release process.

Release process#

In order to release a new version of cotainr, one must:

  1. Create a new branch and run the doc/prepare_release.py script (e.g. via uv run prepare_release.py) to update the docs version switcher and create a release notes skeleton.

  2. Fill in the release notes in the created YYYY.MM.MICRO.md release notes skeleton file in the doc/release_notes folder.

  3. Open a new pull request to merge the release notes and the updated docs version switcher into main and assert successful CI tests of the branch. Then merge it into the main branch.

  4. Tag the main branch locally using git tag YYYY.MM.MICRO and push the tag to the GitHub repository git push origin tag YYYY.MM.MICRO. This triggers the CD on release GitHub action.

  5. Review and approve the TestPyPI and PyPI deployments. Then review and verify that CD on release creates a GitHub release. Finally review that readthedocs is updated correctly, i.e. assert that the stable and latest docs versions points to the newly released version.

Versioning scheme#

A CalVer versioning scheme is used for cotainr, more specifically:

YYYY.MM.MICRO

with:

  • YYYY - full year - 2022, 2023, …

  • MM - short month - 1, 2 … 11, 12

  • MICRO - zero-indexed counter specific to YYYY.MM - 0, 1, … - incremented for each version released in a given year/month.

Version single-sourcing#

The cotainr version (in code and docs) is single-sourced using the logic in the cotainr._version module. The version number is generated according to the following logic:

  1. If the cotainr git history is available and the hatch-vcs package is installed, the version number is generated from the latest YYYY.MM.MICRO release tag in the git history. Pre-release version numbers are generated using the guess-next-dev implementation, i.e.:

    • If additional commits since the latest release tag are present in the git history, the MICRO version is incremented and the version number is suffixed with a .dev<N>+g<commit_sha> string, where <N> is the number of commits since the latest release tag and <commit_sha> is the short hash of the latest commit in the git history.

    • If uncommitted changes are present in the working directory, the version number is further suffixed with a .d<YYYYMMDD> string, where <YYYYMMDD> is the current date.

  2. If the cotainr git history is not available, but cotainr wheel/sdist package metadata is available, i.e., cotainr is installed from a wheel, the YYYY.MM.MICRO version number is read from the package metadata.

  3. If the cotainr git history is not available and no cotainr package metadata is available, the version number is reported as “<unknown version>”.

When building the cotainr wheel/sdist packages, the version number is automatically extracted using the hatch-vcs package.

When running the prepare_release.py script, the version number is automatically created based on the –release_date argument (or the current date, if no release date is specified) and the latest release tag in the git history.