Skip to content

Release Process

Maintainers only

This guide is for repository maintainers with push access to the main branch.

Prerequisites

Before starting a release:

  • All CI checks passing on main
  • main branch is stable
  • All changes committed and pushed
  • You have push access to the repository

Release Types

Type Version Bump Example When to use
Patch 0.1.X 0.1.0 → 0.1.1 Bug fixes only, fully backwards compatible
Minor 0.X.0 0.1.0 → 0.2.0 New features, backwards compatible
Major X.0.0 0.9.0 → 1.0.0 Breaking changes — requires migration guide

Step-by-Step

1. Prepare

git checkout main
git pull origin main
just test && just check

2. Create the release

just release 0.2.0

This command:

  1. Runs all tests
  2. Generates CHANGELOG.md from conventional commits
  3. Bumps version in all pyproject.toml files
  4. Creates git commit + tag v0.2.0

3. Review

git log --oneline -5   # verify commit
git tag | tail -1      # verify tag

4. Push

git push origin main
git push origin --tags

5. Publish GitHub Release

The .github/workflows/release.yml workflow detects the new tag and creates a draft release. Review and publish at github.com/nfb2021/canvodpy/releases.

6. Post-release

  • Monitor issues for regressions
  • Create a Zenodo snapshot for DOI (Zenodo Setup)
  • Update citation information if needed

Troubleshooting

Tests fail during release

Fix the failing tests on main before retrying just release.

Version bump fails

Use an explicit X.Y.Z format (no v prefix): 

just release 0.2.0    # correct
just release v0.2.0   # wrong

Tag already exists 
git tag -d v0.2.0             # delete local tag
git push origin :v0.2.0       # delete remote tag (if already pushed)
just release 0.2.0            # recreate
Workflow did not trigger

Verify the tag matches the pattern v*.*.* at github.com/nfb2021/canvodpy/actions.

Manual Release (Fallback)

just changelog v0.2.0

Then create a release manually at github.com/nfb2021/canvodpy/releases/new.