ci: add semantic-release workflow and conventional commit enforcement

Replace manual patch version bumps with python-semantic-release and
enforce conventional commit messages via commitizen pre-commit hook.

Closes #200

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chriscarrollsmith

.github/workflows/release.yml

@@ -3,14 +3,28 @@ name: release
 on:
   push:
     branches: [main]
+  workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  test:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    uses: ./.github/workflows/test.yml
+
   release:
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
     runs-on: ubuntu-latest
+    needs: test
+
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+
+    permissions:
+      contents: write
+
     steps:
       - name: Generate token for version incrementer app
         id: create_token
@@ -19,64 +33,61 @@ jobs:
           app_id: ${{ secrets.APP_ID }}
           private_key: ${{ secrets.PRIVATE_KEY }}
 
-      - name: Checkout repository
+      - name: Setup | Checkout Repository on Release Branch
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.ref_name }}
           fetch-depth: 0
-          ref: ${{ github.sha }}
           token: ${{ steps.create_token.outputs.token }}
 
-      - name: Force correct branch on workflow sha
-        run: git checkout -B ${{ github.ref_name }} ${{ github.sha }}
-
-      - name: Bump patch version
-        id: bump
+      - name: Sync to latest remote
         run: |
-          CURRENT_VERSION=$(grep -oP '^version = "\K[^"]+' pyproject.toml)
-          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
-          NEW_PATCH=$((PATCH + 1))
-          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          sed -i "s/^version = \"$CURRENT_VERSION\"/version = \"$NEW_VERSION\"/" pyproject.toml
-          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
-          echo "tag=v$NEW_VERSION" >> "$GITHUB_OUTPUT"
-          echo "Bumped version: $CURRENT_VERSION -> $NEW_VERSION"
+          git fetch --prune origin
+          git checkout ${{ github.ref_name }}
+          git merge --ff-only origin/${{ github.ref_name }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5
 
-      - name: Sync uv lockfile
-        run: uv lock
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
 
-      - name: Get merged PR info
-        id: pr_info
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Action | Semantic Version Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.4.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+          commit: "false"
+          push: "false"
+          tag: "false"
+          changelog: "true"
+          vcs_release: "false"
+
+      - name: Commit and push version changes
+        if: steps.release.outputs.released == 'true'
         run: |
-          PR_NUMBER=$(gh pr list --state merged --search "${{ github.sha }}" --json number --jq '.[0].number' 2>/dev/null || echo "")
-          if [ -n "$PR_NUMBER" ]; then
-            PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
-            echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
-            {
-              echo "notes<<EOF"
-              echo "$PR_BODY"
-              echo "EOF"
-            } >> "$GITHUB_OUTPUT"
-          else
-            echo "notes=Release ${{ steps.bump.outputs.tag }}" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Create GitHub release
+          git config user.name "github-actions"
+          git config user.email "actions@users.noreply.github.com"
+          uv lock
+          git add pyproject.toml CHANGELOG.md uv.lock
+          git commit -m "chore: release ${{ steps.release.outputs.tag }} [skip ci]
+
+          Automatically generated by python-semantic-release"
+          git tag ${{ steps.release.outputs.tag }}
+          git push origin ${{ github.ref_name }} --tags
+
+      - name: Create GitHub Release
+        if: steps.release.outputs.released == 'true'
+        run: |
+          gh release create ${{ steps.release.outputs.tag }} \
+            --title "${{ steps.release.outputs.tag }}" \
+            --generate-notes
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          RELEASE_NOTES: ${{ steps.pr_info.outputs.notes }}
-        run: |
-          gh release create "${{ steps.bump.outputs.tag }}" \
-            --title "${{ steps.bump.outputs.tag }}" \
-            --notes "$RELEASE_NOTES"
-
-      - name: Commit version bump
-        uses: stefanzweifel/git-auto-commit-action@v5
-        with:
-          commit_message: "chore: release ${{ steps.bump.outputs.tag }} [skip ci]"
-          branch: ${{ github.ref_name }}
-          file_pattern: "pyproject.toml uv.lock"

.github/workflows/test.yml

@@ -5,6 +5,7 @@ on:
   pull_request:
     branches: [main]
   workflow_dispatch:
+  workflow_call:
 
 jobs:
   test:

.pre-commit-config.yaml

@@ -1,4 +1,14 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
 repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.10.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
   - repo: local
     hooks:
       - id: ruff-format

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- version list -->

pyproject.toml

@@ -36,6 +36,7 @@ dev = [
     "pytest-jinja-check[fastapi]>=1.0.3",
     "pytest-playwright>=0.7.2",
     "pre-commit>=4.6.0",
+    "python-semantic-release>=10.5.3",
 ]
 
 [tool.ty.rules]
@@ -55,3 +56,68 @@ include = ["tests/**"]
 invalid-argument-type = "ignore"
 unresolved-attribute = "ignore"
 missing-argument = "ignore"
+
+[tool.semantic_release]
+assets = []
+build_command_env = []
+build_command = ""
+commit_message = "chore: release {version} [skip ci]\n\nAutomatically generated by python-semantic-release"
+commit_parser = "conventional"
+logging_use_named_masks = false
+major_on_zero = true
+allow_zero_version = false
+no_git_verify = false
+tag_format = "v{version}"
+version_toml = ["pyproject.toml:project.version:nf"]
+
+[tool.semantic_release.branches.main]
+match = "(main|master)"
+prerelease_token = "rc"
+prerelease = false
+
+[tool.semantic_release.changelog]
+exclude_commit_patterns = []
+mode = "update"
+insertion_flag = "<!-- version list -->"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+output_format = "md"
+mask_initial_release = true
+
+[tool.semantic_release.changelog.environment]
+block_start_string = "{%"
+block_end_string = "%}"
+variable_start_string = "{{"
+variable_end_string = "}}"
+comment_start_string = "{#"
+comment_end_string = "#}"
+trim_blocks = false
+lstrip_blocks = false
+newline_sequence = "\n"
+keep_trailing_newline = false
+extensions = []
+autoescape = false
+
+[tool.semantic_release.commit_author]
+env = "GIT_COMMIT_AUTHOR"
+default = "semantic-release <semantic-release>"
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+other_allowed_tags = ["build", "chore", "ci", "docs", "style", "refactor", "test"]
+allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]
+default_bump_level = 0
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+insecure = false
+
+[tool.semantic_release.publish]
+dist_glob_patterns = []
+upload_to_vcs_release = false