Merge pull request #56 from awslabs/feat/setuptools-scm-versioning

build: derive version from git tags via setuptools-scm

Author: DataGomes

.github/workflows/publish.yml

@@ -13,6 +13,10 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+        with:
+          # setuptools-scm needs full history + tags to derive the version
+          # from the latest v* tag. Default checkout depth=1 hides them.
+          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
@@ -27,12 +31,10 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v4
 
-      - name: Set version from tag and sync lockfile
+      - name: Verify tag matches the commit
         run: |
           TAG="${GITHUB_REF#refs/tags/v}"
-          echo "Setting version to $TAG"
-          sed -i "s/^version = .*/version = \"$TAG\"/" pyproject.toml
-          uv lock
+          echo "Building for tag v$TAG (setuptools-scm will derive version from git)"
 
       - name: Build viewer frontend
         run: |

AGENTS.md

@@ -25,18 +25,24 @@ Update both files:
 
 ## Releasing
 
+The version lives in git tags. `pyproject.toml` has no `version` field —
+`setuptools-scm` derives it from the latest `v*` tag at build time.
+
 After merging a PR with user-visible changes, publish to PyPI from main:
 
 ```bash
 git checkout main && git pull
-make release         # patch bump (0.3.0 → 0.3.1) — bug fixes only
-make release-minor   # minor bump (0.3.0 → 0.4.0) — new features, backwards-compat
-make release-major   # major bump (0.3.0 → 1.0.0) — breaking changes
+make release         # patch bump (0.3.4 → 0.3.5) — bug fixes only
+make release-minor   # minor bump (0.3.4 → 0.4.0) — new features, backwards-compat
+make release-major   # major bump (0.3.4 → 1.0.0) — breaking changes
 ```
 
-Each target bumps `pyproject.toml`, commits, tags `vX.Y.Z`, and pushes.
-The `publish.yml` GitHub workflow takes over from the tag push and
-publishes to PyPI via trusted publisher. Don't tag manually.
+Each target reads the latest tag, computes the next, tags it, and pushes
+the tag. No source file is bumped; no "Release vX.Y.Z" commits land on
+main. The `publish.yml` workflow runs on tag push and publishes to PyPI
+via trusted publisher (setuptools-scm bakes the tag's version into the
+built artifacts).
 
 Pick the bump from semver: new public API = minor, only bug fixes =
-patch, backwards-incompatible = major.
+patch, backwards-incompatible = major. Don't tag manually outside the
+Makefile — the targets enforce clean tree + on main + up-to-date.

Makefile

@@ -47,15 +47,19 @@ build:           ## Build all images
 clean: stop      ## Stop and remove volumes
 	@$(COMPOSE) down -v
 
-release:         ## Bump patch version, tag, and push (triggers PyPI publish)
+release:         ## Tag a patch release and push (triggers PyPI publish)
 	@$(MAKE) _release BUMP=patch
 
-release-minor:   ## Bump minor version, tag, and push
+release-minor:   ## Tag a minor release and push
 	@$(MAKE) _release BUMP=minor
 
-release-major:   ## Bump major version, tag, and push
+release-major:   ## Tag a major release and push
 	@$(MAKE) _release BUMP=major
 
+# Version lives in git tags. We read the latest v* tag, bump the requested
+# component, push the new tag — and that's it. No source edits, no
+# "Release vX.Y.Z" commits. The publish.yml workflow runs on tag push and
+# setuptools-scm reads the version straight from the tag at build time.
 _release:
 	@if [ -n "$$(git status --porcelain)" ]; then \
 	  echo "Working tree is dirty. Commit or stash first."; exit 1; \
@@ -64,15 +68,13 @@ _release:
 	  echo "Release must be run from main (currently on $$(git rev-parse --abbrev-ref HEAD))."; exit 1; \
 	fi
 	@git pull --ff-only origin main
-	@OLD=$$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])") && \
+	@git fetch --tags origin
+	@OLD=$$(git tag -l 'v*' | sed 's/^v//' | sort -V | tail -n1) && \
+	if [ -z "$$OLD" ]; then OLD="0.0.0"; fi && \
 	NEW=$$(python3 -c "v='$$OLD'.split('.'); part='$(BUMP)'; \
 	  idx={'major':0,'minor':1,'patch':2}[part]; v[idx]=str(int(v[idx])+1); \
 	  [v.__setitem__(i,'0') for i in range(idx+1,3)]; print('.'.join(v))") && \
-	echo "Bumping $$OLD -> $$NEW" && \
-	python3 -c "import re,pathlib; p=pathlib.Path('pyproject.toml'); p.write_text(re.sub(r'^version = \".*\"', 'version = \"'+'$$NEW'+'\"', p.read_text(), count=1, flags=re.M))" && \
-	git add pyproject.toml && \
-	git commit -m "Release v$$NEW" && \
+	echo "Releasing v$$NEW (previous: v$$OLD)" && \
 	git tag "v$$NEW" && \
-	git push origin main && \
 	git push origin "v$$NEW" && \
 	echo "Pushed v$$NEW. Watch https://github.com/awslabs/llm-evaluation-system/actions"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "llm-evaluation-system"
-version = "0.3.0"
+dynamic = ["version"]
 description = "MCP server for agentic LLM evaluation: jury scoring, agent tracing via OpenTelemetry, document-grounded QA generation, PDF reports."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -83,9 +83,16 @@ eval-mcp = "eval_mcp.cli:main"
 eval-chat = "backend.core.main:main"
 
 [build-system]
-requires = ["setuptools>=68.0.0", "wheel"]
+requires = ["setuptools>=68.0.0", "setuptools-scm>=8.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools_scm]
+# Version is derived from the latest `v*` git tag. When building on a tagged
+# commit the version is clean (e.g. "0.3.5"); off-tag commits get a dev
+# version (e.g. "0.3.6.dev3+gabc1234"). `fallback_version` covers sdist
+# builds and shallow clones where git history isn't available.
+fallback_version = "0.0.0+unknown"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["backend*", "eval_mcp*"]