Release Process

This page covers how a change on main becomes a tagged release and a published Docker image — relevant if you're maintaining a fork or trying to understand why a manually-created tag didn't produce a release.

Versioning Scheme

The version lives in exactly two places, and they must always agree: src/qbt_rules/__version__.py and pyproject.toml. Versions follow PEP 440 (X.Y.Z, with optional aN/bN/rcN/.postN/.devN suffixes for pre-releases).

Bumping the Version

Use the provided script rather than editing the files by hand:

./scripts/bump-version.sh patch   # X.Y.Z -> X.Y.(Z+1)
./scripts/bump-version.sh minor   # X.Y.Z -> X.(Y+1).0
./scripts/bump-version.sh major   # X.Y.Z -> (X+1).0.0

This updates both version files, commits (chore: Bump version to X.Y.Z), and creates an annotated tag vX.Y.Z — but doesn't push anything. Review before pushing:

git log -1
git tag -n vX.Y.Z
git push && git push --tags

What Happens on Tag Push

Pushing a v* tag triggers two workflows:

1. release.yml — re-validates that __version__.py and pyproject.toml both match the pushed tag (this is why manually creating a tag without running bump-version.sh first fails here: the version files won't have been bumped, so they won't match). It then installs the package, smoke-tests the critical imports, generates release notes by grouping commits since the previous tag under Conventional Commit prefixes (feat/fix/refactor/chore), and publishes a GitHub Release. A tag containing a, b, or rc is automatically marked as a pre-release.
2. docker-build.yml — builds and pushes the image to ghcr.io/andronics/qbt-rules with several tags at once (see below).

Because the release notes are generated from commit messages, prefixing commits with feat:/fix:/refactor:/chore: (as bump-version.sh's own commit does) directly determines which section of the changelog a change shows up under.

Docker Tag Reference

A single tagged release (say v1.2.3) produces all of these at once:

Tag	Meaning	Stability
1.2.3	Exact version	Immutable — pin production deployments to this
1.2	Latest patch within this minor version	Moves forward on every 1.2.x patch release
1	Latest minor/patch within this major version	Moves forward on every 1.x.x release
latest	Most recent tagged release	Moves on every release
edge	Most recent build of the default branch	Moves on every push to main, may be unstable

For anything long-running, pin to the exact version tag (1.2.3) rather than latest or edge — those are floating tags that change out from under a deployment on the next release, and edge in particular can be ahead of anything that's actually been released.