Versioning#

FlagGems uses setuptools-scm to auto-generate version numbers from git tags following PEP 440.

Version Format#

No version is hardcoded in any source file. The version is derived entirely from git tags at build time.

The +g<hash> suffix (local version label) is included in local and editable installs, allowing developers to git checkout <hash> for debugging. This suffix is automatically stripped when publishing to PyPI.

Tag Naming Rules#

Development Cycle#

After each stable release, create a dev tag to mark the start of the next version cycle. Never place the dev tag on the same commit as the release tag — when a patch release follows, git tag -f would be needed to move the dev tag, and that two-step fix is easily forgotten.

After pushing the release tag, immediately create an empty commit as the anchor for the dev tag:

# Release tag is already pushed (v5.4.0), continue:
git commit --allow-empty -m "Start v5.5.0 development cycle"
git tag v5.5.0.dev0
git push origin master v5.5.0.dev0

v5.4.0              ← stable release
  │
  │  Start v5.5.0 development cycle  ← empty commit
  │  v5.5.0.dev0                     ← dev tag on this commit
  │
  ├── commit 1  ← 5.5.0.dev1+gabcdef0
  ├── commit 2  ← 5.5.0.dev2+g1234567
  ├── ...
  ├── commit N
  │
v5.5.0              ← next stable release

Release Process#

Releasing a new version (e.g. v5.4.0)#

1. Ensure all PRs for the release are merged into master.

2. Tag the release:

   git checkout master
   git pull origin master
   git tag v5.4.0
   git push origin v5.4.0

3. CI builds release artifacts automatically. The release.yaml workflow triggers on stable version tags (v<major>.<minor>.<patch>) and builds the wheel, then publishes to PyPI.

4. Start the next dev cycle:

   git commit --allow-empty -m "Start v5.5.0 development cycle"
   git tag v5.5.0.dev0
   git push origin master v5.5.0.dev0

   From this point, all commits on master produce versions like 5.5.0.dev1+gabcdef0.

Releasing a patch (e.g. v5.4.1)#

1. Create a release branch if needed:

   git checkout -b release/5.4 v5.4.0

2. Cherry-pick or merge fixes.
3. Tag and push:

   git tag v5.4.1
   git push origin v5.4.1

Release candidates#

Tag as v5.4.0rc1, v5.4.0rc2, etc. These are PEP 440 pre-releases and will not trigger the release workflow (it only matches stable tags). To build RC wheels, trigger the workflow manually or adjust the tag filter temporarily.

Checking the Current Version#

# From a git checkout (diagnostic, not required for install):
python -m setuptools_scm

# From an installed package:
python -c "import flag_gems; print(flag_gems.__version__)"