feat(ci): automated semantic release and versioned Docker tags

.github/workflows/docker.yml

@@ -9,13 +9,11 @@ on:
   push:
     branches: [main]
     paths:
-      - 'pyproject.toml'
-      - 'pixi.lock'
-      - 'src/**'
-      - 'scripts/**'
       - 'Dockerfile'
       - 'docker-entrypoint.sh'
       - '.github/workflows/docker.yml'
+    tags:
+      - 'v*.*.*'
   workflow_dispatch:
 
 env:
@@ -30,29 +28,39 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       # The Dockerfile uses COPY --from=diffuseproject/sampleworks-checkpoints:latest
       # which Docker automatically pulls from Docker Hub during the build.
       # No checkpoint files are needed in the CI build context.
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.DOCKERHUB_ORG }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest
+            type=sha,prefix=
+            type=semver,pattern={{version}}
+            type=semver,pattern=v{{version}}
       - name: Build and push Docker image
         id: build-push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           push: true
-          tags: |
-            ${{ env.DOCKERHUB_ORG }}/${{ env.IMAGE_NAME }}:latest
-            ${{ env.DOCKERHUB_ORG }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
           provenance: false

.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - run: git reset --hard ${{ github.sha }}
+
+      - name: Semantic Release
+        id: release
+        uses: python-semantic-release/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "[email protected]"
+
+      - name: Publish to GitHub Releases
+        if: steps.release.outputs.released == 'true'
+        uses: python-semantic-release/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release.outputs.tag }}

.pre-commit-config.yaml

@@ -20,6 +20,12 @@ repos:
         additional_dependencies:
           - toml-sort==0.24.3
 
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.9
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.0
     hooks:

AGENTS.md

@@ -233,6 +233,80 @@ pixi run -e boltz-dev prek run -a       # Run all hooks on all files
 
 Note: `ty` type checking is split per environment — Boltz files are checked in `boltz-dev`, Protenix files in `protenix-dev`, RF3 files in `rf3-dev`. See `.pre-commit-config.yaml` for the file routing rules.
 
+## Release Process
+
+Releases are fully automated via [python-semantic-release](https://python-semantic-release.readthedocs.io/) (PSR v10). No manual version bumps or changelog edits are needed.
+
+### Conventional Commits (Required)
+
+All commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>(<optional scope>): <summary>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types and their effect on versioning:**
+
+| Type | Description | Version bump |
+|------|-------------|-------------|
+| `feat` | New feature | Minor (0.x.0) |
+| `fix` | Bug fix | Patch (0.x.x) |
+| `docs` | Documentation only | None |
+| `refactor` | Code change (no new feature or fix) | None |
+| `test` | Adding/updating tests | None |
+| `chore` | Maintenance (CI, deps, tooling) | None |
+| `perf` | Performance improvement | Patch (0.x.x) |
+
+**Breaking changes** (append `!` after type, e.g. `feat!:`) bump the minor version while we're in 0.x (`major_on_zero = false`).
+
+**Examples:**
+```bash
+feat(rewards): add cryo-EM image stack reward function
+fix(boltz): correct atom reconciler index mapping for OXT atoms
+docs: update AGENTS.md with new model wrapper example
+refactor(scalers)!: rename StepScaler to StepGuide
+chore(ci): pin Docker build action to v5
+```
+
+A **commitizen** pre-commit hook validates commit messages locally. Install it with:
+```bash
+pixi run -e boltz-dev prek install --hook-type commit-msg
+```
+
+### How Releases Work
+
+1. Push/merge to `main` with `feat:` or `fix:` commits
+2. The **Release** workflow runs PSR, which:
+   - Analyzes commits since the last tag
+   - Determines the version bump (or skips if no releasable commits)
+   - Updates `version` in `pyproject.toml`
+   - Updates `CHANGELOG.md`
+   - Creates a version commit and `v{version}` tag
+   - Pushes the commit and tag
+3. The **Docker** workflow triggers on the new `v*.*.*` tag and builds images tagged with the version
+
+### What Does NOT Trigger a Release
+
+Commits with types `docs`, `refactor`, `test`, `chore`, `ci`, or `style` do not bump the version. They will appear in the next changelog under their respective sections when a releasable commit is included.
+
+### Version Strategy
+
+We use `major_on_zero = false`, meaning breaking changes bump minor (not major) while the version is 0.x. This will change when we decide to release 1.0.
+
+### Merge Strategy
+
+Use **squash merge** for all PRs. This collapses a PR's commits into a single commit on `main`, with the PR title as the commit message. The PR title **must** follow Conventional Commits format and controls the version bump:
+
+- `feat(rewards): add cryo-EM image stack reward` → minor bump
+- `fix(boltz): correct OXT atom mapping` → patch bump
+- `docs: update installation guide` → no release
+
+This keeps the changelog clean (one entry per PR), the version history predictable (one potential bump per PR), and requires no discipline around individual commit messages during development. PRs should be focused on a single logical change — avoid PRs that bundle unrelated features and fixes.
+
 ## Testing Philosophy
 
 Write black-box tests that verify **behavior**, not implementation. Test public interfaces with realistic inputs. Verify outputs match contracts — shapes, value ranges, mathematical properties.

CHANGELOG.md

@@ -0,0 +1,3 @@
+# CHANGELOG
+
+<!--next-version-placeholder-->

README.md

@@ -150,6 +150,7 @@ pixi run test-all            # run all tests across all environments
 
 ```bash
 pixi run -e [model]-dev prek install
+pixi run -e [model]-dev prek install --hook-type commit-msg
 pixi run -e [model]-dev prek run --all-files
 ```
 
@@ -171,3 +172,14 @@ To develop on OS X, ensure you have [homebrew](https://brew.sh/) installed and r
 There are different (and as yet untested) environments for `boltz`. `protenix` won't currently work on a Mac due to
 the strict requirement of `triton` which requires an NVIDIA GPU. You may find similar issues with other environments.
 Debug as needed.
+
+
+## Commit Messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and changelog generation. Format:
+
+```
+<type>(<scope>): <summary>
+```
+
+Common types: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`, `perf`. A commitizen pre-commit hook validates messages at commit time. See [AGENTS.md](AGENTS.md#release-process) for full details.