Release Process

Bump Version Number

Change the version number in the following files:

  • src/cast/__init__.py

  • docs/conf.py

  • pyproject.toml

The README.md “Upgrade note” heading is intentionally not bumped each release: it stays pinned to the version that introduced the breaking change it describes (e.g. Upgrade note (0.2.54)). Replace that section only when a newer breaking change warrants it.

Update the release notes date in docs/releases/<version>.rst from “(unreleased)” to today’s date (e.g. 0.2.53 (2026-02-26)). This must happen before tagging the release. Verify the file is listed in docs/releases/index.rst.

Commit and push all release-prep changes on develop before proceeding.

Run Checks

Make sure lint, type checking, and tests pass:

$ just check

JavaScript

Update dependencies and rebuild all shipped assets:

$ cd javascript
$ npm outdated
$ npm update
$ cd ..
$ just js-build-all

Test Python Versions

Make sure all tests pass on supported Python versions:

$ uv run tox

Merge develop into main

$ git checkout main
$ git pull && git merge origin/develop
$ git push

Create the Release on GitHub

Use gh to create a tagged pre-release. Use previous releases as a template for the notes (Highlights / Improvements / Fixes / Docs sections):

$ gh release create <version> --target main \
    --title "<version> (YYYY-MM-DD)" \
    --prerelease \
    --notes "$(cat <<'EOF'
## <version> (YYYY-MM-DD)

### Highlights
- ...

### Improvements
- ...

### Fixes
- ...

### Docs / Maintenance
- ...
EOF
)"

Build and Publish to PyPI

$ uv build
$ uv publish --token your-token

Prepare Next Development Version

Switch back to develop and bump the version to the next unreleased version:

$ git checkout develop

Update the version number in:

  • pyproject.toml

  • docs/conf.py

  • src/cast/__init__.py

Create a new release notes file docs/releases/<next-version>.rst with “(unreleased)” as the date, and add it to docs/releases/index.rst.

Commit the version bump to develop.

Important

All new development work must happen on the develop branch. Never commit directly to main.