build: use hatch-vcs for dynamic versioning from git tags (#639)

* build: use hatch-vcs for dynamic versioning from git tags

Replace the static version in pyproject.toml with hatch-vcs, which
derives the version from git tags at build time. This eliminates the
drift where pyproject.toml on main stays stale because the release
workflow could only push tags (not branch commits due to branch
protection).

- pyproject.toml: add hatch-vcs, replace static version with dynamic
- checks.yml: BuildWheel gets fetch-depth: 0, TestPyPI uses
  SETUPTOOLS_SCM_PRETEND_VERSION instead of sed
- release.yml: remove sed/commit/git-config — just tag and push
- fallback-version handles shallow clones in non-build CI jobs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use git tag --sort instead of git describe for TestPyPI version

git describe only finds tags reachable from HEAD. Tags 0.13.0 and
0.13.1 live on orphaned commits (created by the old release workflow's
version-bump commit that was never pushed to main), so git describe
finds 0.12.11 instead. git tag --sort=-version:refname finds the
highest semver tag regardless of reachability.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address Codex review — docs version + release retry

- docs/source/conf.py: use importlib.metadata.version() instead of
  reading pyproject.toml (which no longer has a static version field)
- release.yml: on retry, checkout the tagged commit and set
  SETUPTOOLS_SCM_PRETEND_VERSION so the build produces the exact
  release version, not a dev version from HEAD

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: avoid name collision with Sphinx's version config variable

import metadata module instead of the version function directly,
since Sphinx reads 'version' from conf.py's namespace as a config key.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: paddymul

.github/workflows/checks.yml

@@ -62,6 +62,8 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
@@ -80,15 +82,14 @@ jobs:
       - name: Install pnpm dependencies
         working-directory: packages
         run: pnpm install --frozen-lockfile
-      - name: Install the project
-        run: uv sync --all-extras --dev
       - name: Patch version for TestPyPI
         if: github.event_name == 'pull_request'
         run: |
-          BASE=$(grep -Po '^version = "\K[^"]+' pyproject.toml)
-          DEV="${BASE}.dev${{ github.run_id }}"
-          sed -i "s/^version = \".*\"/version = \"${DEV}\"/" pyproject.toml
-          echo "Published version: ${DEV}"
+          BASE=$(git tag --sort=-version:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || echo "0.0.0")
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=${BASE}.dev${{ github.run_id }}" >> "$GITHUB_ENV"
+          echo "Published version: ${BASE}.dev${{ github.run_id }}"
+      - name: Install the project
+        run: uv sync --all-extras --dev
       - name: Build JS extension + Python wheel
         run: ./scripts/full_build.sh
       - name: Upload build artifacts

.github/workflows/release.yml

@@ -64,17 +64,19 @@ jobs:
           # `|| true` prevents pipefail exit when no tags match the pattern.
           LATEST_TAG=$(git tag --sort=-creatordate | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)
           if [ -z "$LATEST_TAG" ]; then
-            CURRENT=$(grep -Po '^version = "\K[^"]+' pyproject.toml)
-            echo "No semver tags found; falling back to pyproject.toml: $CURRENT"
+            CURRENT="0.0.0"
+            echo "No semver tags found; starting from $CURRENT"
           else
             # If the latest tag has no GitHub release, a prior run failed
             # after tagging. Retry that version instead of bumping again.
             if ! gh release view "$LATEST_TAG" &>/dev/null; then
               PREV_TAG=$(git tag --sort=-creatordate | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sed -n '2p' || true)
               echo "::warning::Tag $LATEST_TAG exists without a release — retrying incomplete release."
-              echo "new=$LATEST_TAG" >> "$GITHUB_OUTPUT"
-              echo "prev_tag=${PREV_TAG:-$LATEST_TAG}" >> "$GITHUB_OUTPUT"
-              echo "retry=true" >> "$GITHUB_OUTPUT"
+              {
+                echo "new=$LATEST_TAG"
+                echo "prev_tag=${PREV_TAG:-$LATEST_TAG}"
+                echo "retry=true"
+              } >> "$GITHUB_OUTPUT"
               exit 0
             fi
             CURRENT="$LATEST_TAG"
@@ -91,9 +93,11 @@ jobs:
             echo "::error::Tag $NEW already exists — this release may have already run. Aborting."
             exit 1
           fi
-          echo "new=$NEW" >> "$GITHUB_OUTPUT"
-          echo "prev_tag=$CURRENT" >> "$GITHUB_OUTPUT"
-          echo "retry=false" >> "$GITHUB_OUTPUT"
+          {
+            echo "new=$NEW"
+            echo "prev_tag=$CURRENT"
+            echo "retry=false"
+          } >> "$GITHUB_OUTPUT"
           echo "Bumping $CURRENT → $NEW (${{ inputs.bump }})"
 
       - name: Generate release notes
@@ -106,21 +110,17 @@ jobs:
             --date "$(date +%Y-%m-%d)" \
             --output-dir /tmp
 
-      - name: Bump version, commit, tag, and push
+      - name: Tag and push
         run: |
-          sed -i 's/^version = ".*"/version = "${{ steps.versions.outputs.new }}"/' pyproject.toml
           if [ "${{ steps.versions.outputs.retry }}" = "true" ]; then
-            echo "Retry mode — tag ${{ steps.versions.outputs.new }} already exists, skipping."
+            echo "Retry mode — tag ${{ steps.versions.outputs.new }} already exists, checking out tagged commit."
+            git checkout "${{ steps.versions.outputs.new }}"
           else
-            # Commit the version bump so the tag points to correct source.
-            # Only the tag is pushed — not the branch (branch protection).
-            git config user.name "github-actions[bot]"
-            git config user.email "github-actions[bot]@users.noreply.github.com"
-            git add pyproject.toml
-            git commit -m "chore: release ${{ steps.versions.outputs.new }}"
             git tag "${{ steps.versions.outputs.new }}"
             git push origin "${{ steps.versions.outputs.new }}"
           fi
+          # Pin hatch-vcs to the exact release version for the build step
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=${{ steps.versions.outputs.new }}" >> "$GITHUB_ENV"
 
       - name: Create GitHub release
         env:

docs/source/conf.py

@@ -5,12 +5,12 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-import toml
+from importlib import metadata
 
 project = 'Buckaroo'
 copyright = '2023-2025, Paddy Mullen'
 author = 'Paddy Mullen'
-release = toml.load(open("../../pyproject.toml"))['project']['version']
+release = metadata.version('buckaroo')
 
 
 # -- General configuration ---------------------------------------------------

pyproject.toml

@@ -1,6 +1,7 @@
 [build-system]
 requires = [
     "hatchling",
+    "hatch-vcs",
     "jupyterlab~=4.0",
 ]
 build-backend = "hatchling.build"
@@ -41,7 +42,7 @@ dependencies = [
     "numpy >= 2.2.5; python_version >= '3.13'",
 ]
 
-version = "0.12.12"
+dynamic = ["version"]
 
 
 [project.license]
@@ -120,6 +121,10 @@ buckaroo-table = "buckaroo_mcp_tool:main"
 [project.urls]
 Homepage = "https://github.com/paddymul/buckaroo"
 
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0+unknown"
+
 [tool.hatch.build]
 only-packages = true
 artifacts = ["buckaroo/static/widget.js", "buckaroo/static/compiled.css", "buckaroo/static/standalone.js", "buckaroo/static/standalone.css","scripts/hatch_build.py"]
@@ -172,6 +177,7 @@ line_length = 80
 # Exclude a variety of commonly ignored directories.
 exclude = [
     ".bzr",
+    ".claude",
     ".direnv",
     ".eggs",
     ".git",