Add release versioning targets: make version and make release

- Add scripts/release.sh: Validates semver version, checks for clean git state, creates annotated tag, and pushes to origin
- Add make version target: Queries setuptools_scm to show current calculated version
- Add make release VERSION=x.y.z target: Delegates to release.sh for safe, repeatable releases
- Add setuptools-scm to dev dependencies in pyproject.toml
- Update Makefile help documentation

The release workflow is now clean and logic-free (all logic in scripts/release.sh), enabling safe tag creation and pushing as part of the development workflow.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Author: elifarley

Makefile

@@ -25,12 +25,14 @@ COV_HTML  := htmlcov
 # If HATCH is available, we use it for running commands to ensure isolation.
 # Otherwise, we fall back to the local python environment.
 ifeq (, $(shell command -v $(HATCH) 2> /dev/null))
-    # Hatch not found
+    # Hatch not found - use local python
     RUNNER := $(PY) -m
+    PYTHON_CMD := $(PY)
     BUILD_CMD := $(PY) -m build
 else
-    # Hatch found
+    # Hatch found - use hatch environment
     RUNNER := $(HATCH) run
+    PYTHON_CMD := $(HATCH) run python
     BUILD_CMD := $(HATCH) build
 endif
 
@@ -61,6 +63,10 @@ Targets:
     test-case       Run specific test case (K=pattern)
     coverage-open   Open coverage HTML report
 
+    # Release
+    version         Show current project version (calculated from git)
+    release         Create and push a new release tag (V=x.y.z)
+
     # Build & Dist
     build           Build wheel + sdist (clean first)
     clean           Remove all build artifacts and __pycache__
@@ -71,7 +77,7 @@ Targets:
 endef
 export HELP_MESSAGE
 
-.PHONY: help install dev format check-format lint test quick test-file test-case coverage-open build wheel sdist docs clean distclean ci
+.PHONY: help install dev format check-format lint test quick test-file test-case coverage-open build wheel sdist docs clean distclean ci release version
 
 .DEFAULT_GOAL := help
 
@@ -120,7 +126,15 @@ test-case: ## Run specific test case (K=pattern)
 	$(RUNNER) $(PYTEST) $(PYTEST_ARGS) -k "$(K)" $(ARGS)
 
 coverage-open:
-	@$(PY) -c "import webbrowser, os; f = os.path.join(os.getcwd(), '$(COV_HTML)', 'index.html'); print('Opening:', f); webbrowser.open('file://' + f) if os.path.exists(f) else print('Run make test first.')"
+	@$(PYTHON_CMD) -c "import webbrowser, os; f = os.path.join(os.getcwd(), '$(COV_HTML)', 'index.html'); print('Opening:', f); webbrowser.open('file://' + f) if os.path.exists(f) else print('Run make test first.')"
+
+# ---------- Release ----------
+version v: ## Show current project version
+	@$(PYTHON_CMD) -m setuptools_scm
+
+release: ## Create and push a new release tag
+	@chmod +x scripts/release.sh
+	@./scripts/release.sh $(V)
 
 # ---------- Build & Docs ----------
 build: ## Build dists

pyproject.toml

@@ -31,6 +31,7 @@ dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "build>=1.0.0",
+    "setuptools-scm>=8.0",
 ]
 
 [tool.setuptools_scm]

scripts/release.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -e
+
+# scripts/release.sh
+# Handles the git tagging and pushing for a new release.
+# Usage: ./scripts/release.sh <version>
+
+VERSION="$1"
+
+# 1. Validation
+if [ -z "$VERSION" ]; then
+    echo "Error: V argument is required."
+    echo "Usage: make release V=1.2.3"
+    exit 1
+fi
+
+# Validate SemVer format (X.Y.Z, no 'v' prefix)
+if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+)?$ ]]; then
+    echo "Error: Version '$VERSION' does not match SemVer format (X.Y.Z)."
+    echo "Example: 1.0.0, 0.2.1-rc1"
+    exit 1
+fi
+
+# Check for clean working directory
+if [ -n "$(git status --porcelain)" ]; then
+    echo "Error: Git working directory is not clean."
+    echo "Please commit or stash changes before releasing."
+    exit 1
+fi
+
+# Check if tag already exists
+if git rev-parse "refs/tags/$VERSION" >/dev/null 2>&1; then
+    echo "Error: Tag '$VERSION' already exists."
+    exit 1
+fi
+
+# 2. Execution
+echo "Preparing release $VERSION..."
+
+# Create annotated tag
+git tag -a "$VERSION" -m "Release $VERSION"
+echo "✅ Created git tag: $VERSION"
+
+# Push tag
+echo "Pushing tag to origin..."
+git push origin "$VERSION"
+echo "✅ Pushed tag to origin"
+
+echo "🚀 Release $VERSION triggered! Check GitHub Actions for progress."