Add smoother release workflow with bumpver (#23) (#28)

- Make version dynamic via hatchling regex source (single source of
  truth: tidydraws/__init__.py), removing the literal version from
  pyproject.toml so it can never drift
- Add bumpver config scoped to __init__.py with pre_commit_hook that
  re-derives uv.lock into the same commit
- Add make release-patch/minor/major targets
- Add release.yml workflow: tag push creates GitHub Release with
  auto-generated notes, which then triggers publish.yml
- Simplify publish.yml: removed fragile inline version assertion
- Add scripts/pre-bump.sh (uv lock + git add uv.lock)
- Add venv-*/ to .gitignore to prevent stray venvs breaking uv build
- Add Releasing section to CONTRIBUTING.md
- GitHub: enforce_admins off (admin direct-push for bumps), tag
  protection ruleset (admin-only version tags), release environment
  requires admin approval for PyPI upload

Author: drbenvincent

.github/workflows/publish.yml

@@ -1,5 +1,8 @@
 name: PyPI release
 
+# Builds the package on every PR/push to main to catch breakages early, but
+# only publishes when a GitHub Release is published (which is created by
+# release.yml in response to a v* tag push).
 on:
   workflow_dispatch:
   pull_request:
@@ -30,20 +33,14 @@ jobs:
         run: |
           uv venv venv-sdist
           uv pip install --python venv-sdist/bin/python dist/tidydraws*.tar.gz
-          echo "Checking import and version number (on release)"
-          venv-sdist/bin/python -c "import tidydraws; assert tidydraws.__version__ == '${REF_NAME}' if '${REF_TYPE}' == 'tag' else tidydraws.__version__; print(tidydraws.__version__)"
-        env:
-          REF_NAME: ${{ github.ref_name }}
-          REF_TYPE: ${{ github.ref_type }}
+          echo "Checking import and version number"
+          venv-sdist/bin/python -c "import tidydraws; print(tidydraws.__version__)"
       - name: Check the bdist installs and imports
         run: |
           uv venv venv-bdist
           uv pip install --python venv-bdist/bin/python dist/tidydraws*.whl
-          echo "Checking import and version number (on release)"
-          venv-bdist/bin/python -c "import tidydraws; assert tidydraws.__version__ == '${REF_NAME}' if '${REF_TYPE}' == 'tag' else tidydraws.__version__; print(tidydraws.__version__)"
-        env:
-          REF_NAME: ${{ github.ref_name }}
-          REF_TYPE: ${{ github.ref_type }}
+          echo "Checking import and version number"
+          venv-bdist/bin/python -c "import tidydraws; print(tidydraws.__version__)"
       - uses: actions/upload-artifact@v4
         with:
           name: artifact

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+# Triggered by a version tag push (e.g. 0.5.0) created by `make release-*`.
+# Creates a GitHub Release with auto-generated notes. The "release published"
+# event then fires publish.yml → build → TestPyPI → PyPI.
+#
+# Only admins can push version tags (enforced by the tag protection ruleset),
+# so this workflow cannot be triggered by non-admin collaborators.
+on:
+  push:
+    tags:
+      - "*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${GITHUB_REF_NAME}" --generate-notes --title "${GITHUB_REF_NAME}"

.gitignore

@@ -8,6 +8,7 @@ build/
 *.spec
 .env/
 .venv/
+venv-*/
 .scratch/
 
 # Great Docs build directory (ephemeral, do not commit)

CONTRIBUTING.md

@@ -136,3 +136,43 @@ This repo ships the [Great Docs Agent Skills](https://posit-dev.github.io/great-
 - Ensure all tests pass
 - Add or update documentation as needed
 - Keep changes focused and atomic
+
+## Releasing
+
+Releases are cut by a repo admin running a single `make` target. The version lives in one place — `tidydraws/__init__.py` (`__version__`) — and is read dynamically by hatchling at build time, so `pyproject.toml` never carries a version literal.
+
+### To cut a release (admin only)
+
+```bash
+make release-patch   # 0.4.0 -> 0.4.1
+make release-minor   # 0.4.0 -> 0.5.0
+make release-major   # 0.4.0 -> 1.0.0
+```
+
+This runs `bumpver`, which:
+
+1. Bumps `__version__` in `tidydraws/__init__.py` (the only version literal in the repo).
+2. Runs `scripts/pre-bump.sh`, which re-derives `uv.lock` and stages it so the lockfile lands in the same commit.
+3. Commits with message `Bump version 0.4.0 -> 0.5.0`.
+4. Creates and pushes tag `0.5.0`.
+
+The tag push then triggers the automated cascade:
+
+```mermaid
+flowchart LR
+    A[make release-minor] --> B[bumpver: bump, lock, commit, tag, push]
+    B --> C[release.yml: GitHub Release]
+    C --> D[publish.yml: build sdist+wheel]
+    D --> E[TestPyPI + verify install]
+    E --> F[PyPI upload — gated by release environment review]
+```
+
+The final PyPI upload runs in the `release` [environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment), which requires admin approval in the Actions UI. Nothing reaches PyPI without that click.
+
+### Permissions and gating
+
+- **Admin direct-push to `main`**: `enforce_admins` is off, so admins can push the bump commit directly. Non-admin collaborators still need a PR.
+- **Tag protection**: only admins can push version tags (e.g. `0.5.0`), so only admins can trigger a release.
+- **PyPI environment**: the `release` environment requires admin review before upload.
+
+Non-admin collaborators and external contributors cannot cut releases at any stage.

Makefile

@@ -1,6 +1,6 @@
 # Makefile for tidydraws development workflow
 
-.PHONY: help install test lint type-check precommit docs docs-preview cleandocs build clean
+.PHONY: help install test lint type-check precommit docs docs-preview cleandocs build clean release release-patch release-minor release-major
 
 # Help target to show available commands
 help:
@@ -14,6 +14,11 @@ help:
 	@echo "  docs-preview  - Build and serve the docs locally with live reload"
 	@echo "  cleandocs     - Remove the ephemeral great-docs/ build directory"
 	@echo "  clean         - Clean build artifacts"
+	@echo ""
+	@echo "Releasing (admin only; see CONTRIBUTING.md > Releasing):"
+	@echo "  release-patch  - Bump patch (0.4.0 -> 0.4.1) and cut a release"
+	@echo "  release-minor  - Bump minor (0.4.0 -> 0.5.0) and cut a release"
+	@echo "  release-major  - Bump major (0.4.0 -> 1.0.0) and cut a release"
 
 # Install dependencies
 install:
@@ -52,3 +57,18 @@ clean: cleandocs
 	rm -rf .pytest_cache/
 	find . -name "*.pyc" -delete
 	find . -name "__pycache__" -type d -exec rm -rf {} +
+
+# ── Release ─────────────────────────────────────────────────────────────────
+# Admin only. Bumps the version (single source: tidydraws/__init__.py),
+# re-derives uv.lock, commits, tags, and pushes. The tag push triggers the
+# release.yml workflow → GitHub Release → publish.yml → TestPyPI → PyPI.
+# Requires admin push rights to main (enforce_admins is off) and tag-push
+# rights (tag protection rule on v*).
+release-patch:
+	uv run bumpver update --patch
+
+release-minor:
+	uv run bumpver update --minor
+
+release-major:
+	uv run bumpver update --major

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tidydraws"
-version = "0.4.0"
+dynamic = ["version"]
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -82,6 +82,23 @@ Documentation = "https://drbenvincent.github.io/tidydraws/"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+source = "regex"
+path = "tidydraws/__init__.py"
+pattern = '__version__ = "(?P<version>[^"]+)"'
+
+[tool.bumpver]
+current_version = "0.4.0"
+version_pattern = "MAJOR.MINOR.PATCH"
+commit_message = "Bump version {old_version} -> {new_version}"
+commit = true
+tag = true
+push = true
+pre_commit_hook = "scripts/pre-bump.sh"
+
+[tool.bumpver.file_patterns]
+"tidydraws/__init__.py" = ['__version__ = "{version}"']
+
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
@@ -92,6 +109,7 @@ dev = [
     "altair>=6.2.2",
     "vegafusion>=2.0.3",
     "vl-convert-python>=1.9.0",
+    "bumpver",
 ]
 
 [tool.ruff]

scripts/pre-bump.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# bumpver pre_commit_hook: re-derive uv.lock from the new __version__ and
+# stage it so the version bump, lockfile, and tag all land in one commit.
+# See https://brtkwr.com/posts/2026-01-14-bumpver-with-uv/ for the rationale.
+set -euo pipefail
+uv lock
+git add uv.lock