Automate releases from PR titles and clean up CI workflows.

Add release and PR title checks, shared CI scripts, Gitea PR template, and align pyproject.toml to v0.3.1.

Co-authored-by: Cursor <[email protected]>

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Version bump
+
+If this PR changes files under `python_repositories/`, the **title must** start with one of:
+
+- `[patch]` or `[fix]` — bug fix (0.3.1 → 0.3.2)
+- `[minor]` or `[feat]` — new feature (0.3.1 → 0.4.0)
+- `[major]` or `[breaking]` — breaking change (0.3.1 → 1.0.0)
+
+Docs-, CI-, or test-only PRs do not need a prefix.
+
+**Example title:** `[minor] Add streaming support to RedisAdapter`
+
+## Summary
+
+<!-- What changed and why -->
+
+## Test plan
+
+- [ ] Integration tests pass locally

.gitea/workflows/code-quality.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ inputs.python-version }}
+          python-version-file: .python-version
 
       - name: Install uv
         run: pip install uv
@@ -36,7 +36,7 @@ jobs:
         run: uv run ruff format --check .
 
       - name: Pyupgrade check
-        run: uv run pyupgrade --py313-plus $(git ls-files '*.py') && git diff --exit-code
+        run: uv run pyupgrade --py312-plus $(git ls-files '*.py') && git diff --exit-code
 
       - name: Prettier format
         run: uv run pre-commit run prettier --all-files

.gitea/workflows/dependency-update-bot.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ inputs.python-version }}
+          python-version-file: .python-version
 
       - name: Install uv and pip-review
         run: |

.gitea/workflows/pr-title-check.yml

@@ -0,0 +1,23 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check PR title when source files change
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          git fetch origin "${{ github.base_ref }}"
+          git diff --name-only "origin/${{ github.base_ref }}...HEAD" \
+            | scripts/ci/check-pr-title.sh "$PR_TITLE"

.gitea/workflows/publish.yml

@@ -17,17 +17,13 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ inputs.python-version }}
+          python-version-file: .python-version
 
       - name: Install uv
         run: pip install uv
 
       - name: Update version in pyproject.toml to match tag
-        run: |
+        run: scripts/ci/bump-version.sh --from-tag "${GITHUB_REF##*/}"
-          TAG_VERSION="${GITHUB_REF##*/}"
-          VERSION="${TAG_VERSION#v}"
-          sed -i.bak -E "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
-          rm pyproject.toml.bak
 
       - name: Build package
         run: |

.gitea/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release on merge to main
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CI_RUNNER_TOKEN }}
+
+      - name: Parse merge commit
+        id: meta
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
+        run: scripts/ci/parse-merge-commit.sh "$COMMIT_MSG"
+
+      - name: Bump version
+        if: steps.meta.outputs.bump != 'skip'
+        id: bump
+        run: scripts/ci/bump-version.sh "${{ steps.meta.outputs.bump }}"
+
+      - name: Generate release notes
+        if: steps.meta.outputs.bump != 'skip'
+        id: notes
+        env:
+          PR_TITLE: ${{ steps.meta.outputs.pr_title }}
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0)
+          NEW_TAG="v${{ steps.bump.outputs.version }}"
+          scripts/ci/generate-release-notes.sh "$NEW_TAG" "$PR_TITLE" "$PREV_TAG"
+
+      - name: Commit, tag, and push
+        if: steps.meta.outputs.bump != 'skip'
+        env:
+          VERSION: ${{ steps.bump.outputs.version }}
+          CI_RUNNER_TOKEN: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: |
+          git config user.name "CI Bot"
+          git config user.email "[email protected]"
+          git add pyproject.toml
+          git commit -m "chore: release v${VERSION} [skip ci]"
+          git tag "v${VERSION}"
+          git remote set-url origin "https://x-access-token:${CI_RUNNER_TOKEN}@${GITHUB_SERVER_URL#https://}/${GITHUB_REPOSITORY}.git"
+          git push origin main
+          git push origin "v${VERSION}"
+
+      - name: Create Gitea release
+        if: steps.meta.outputs.bump != 'skip'
+        env:
+          API_URL: ${{ vars.API_URL }}
+          REPO_OWNER: ${{ github.repository_owner }}
+          REPO_NAME: ${{ github.event.repository.name }}
+          CI_RUNNER_TOKEN: ${{ secrets.CI_RUNNER_TOKEN }}
+          VERSION: ${{ steps.bump.outputs.version }}
+          PR_TITLE: ${{ steps.meta.outputs.pr_title }}
+          RELEASE_BODY: ${{ steps.notes.outputs.body }}
+        run: |
+          SUMMARY=$(echo "$PR_TITLE" | sed -E 's/^\[(patch|fix|minor|feat|major|breaking)\][[:space:]]*//i')
+          export RELEASE_NAME="v${VERSION} — ${SUMMARY}"
+          PAYLOAD=$(python3 -c 'import json, os; print(json.dumps({"tag_name": "v" + os.environ["VERSION"], "name": os.environ["RELEASE_NAME"], "body": os.environ["RELEASE_BODY"]}))')
+          curl -s -X POST \
+            "${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/releases" \
+            -H "Authorization: token ${CI_RUNNER_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$PAYLOAD"

.gitea/workflows/security-audit copy.yml

@@ -1,29 +0,0 @@
-name: Security Audit
-
-on:
-  schedule:
-    - cron: "0 0 * * 0" # Weekly
-  workflow_dispatch:
-
-jobs:
-  safety:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ inputs.python-version }}
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
-        env:
-          UV_LINK_MODE: copy
-        run: uv sync
-
-      - name: Run safety check
-        run: uv run safety check

.gitea/workflows/security-audit.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ inputs.python-version }}
+          python-version-file: .python-version
 
       - name: Install uv
         run: pip install uv

.gitea/workflows/sync-pyproject-version.yml

@@ -1,38 +0,0 @@
-name: Sync pyproject.toml Version
-
-on:
-  workflow_run:
-    workflows: ["Publish Python Package"]
-    types:
-      - completed
-
-jobs:
-  commit-version-update:
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ inputs.python-version }}
-
-      - name: Configure git
-        run: |
-          git config user.name "CI Bot"
-          git config user.email "[email protected]"
-
-      - name: Update version in pyproject.toml to match tag
-        run: |
-          TAG_VERSION="${{ github.event.workflow_run.head_branch }}"
-          VERSION="${TAG_VERSION#v}"
-          sed -i.bak -E "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
-          rm pyproject.toml.bak
-
-      - name: Commit and push changes
-        run: |
-          git add pyproject.toml
-          git commit -m "chore: update version in pyproject.toml to ${VERSION} [skip ci]" || echo "No changes to commit"
-          git push

.gitea/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ inputs.python-version }}
+          python-version-file: .python-version
 
       - name: Install uv
         run: pip install uv
@@ -32,6 +32,7 @@ jobs:
         run: uv run pytest --cov=python_repositories --cov-report=term-missing > coverage.txt
 
       - name: Post coverage summary to PR
+        if: github.event_name == 'pull_request'
         env:
           API_URL: ${{ vars.API_URL }}
           REPO_OWNER: ${{ github.repository_owner }}

.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
     rev: v3.20.0
     hooks:
       - id: pyupgrade
-        args: ["--py311-plus"]
+        args: ["--py312-plus"]
 
   # Formatting for Markdown, JSON, and YAML with Prettier
   - repo: https://github.com/pre-commit/mirrors-prettier

README.md

@@ -112,3 +112,38 @@ uv run pre-commit run --all-files
 ```
 
 Integration tests require Docker (testcontainers).
+
+## Releases
+
+Releases are automated when a pull request is merged to `main`. CI reads the **merged PR title** to decide whether and how to bump the version.
+
+### How it works
+
+1. Open a PR targeting `main` (see [`.gitea/PULL_REQUEST_TEMPLATE.md`](.gitea/PULL_REQUEST_TEMPLATE.md)).
+2. If the PR changes files under `python_repositories/`, the title **must** start with a version bump prefix (enforced by CI).
+3. On merge, [`release.yml`](.gitea/workflows/release.yml) bumps [`pyproject.toml`](pyproject.toml), commits, tags `vX.Y.Z`, creates a Gitea release with auto-generated notes, and pushes the tag.
+4. [`publish.yml`](.gitea/workflows/publish.yml) builds and publishes the package to the Gitea Package Registry.
+
+Docs-, CI-, and test-only PRs do not need a prefix and will not trigger a release.
+
+### PR title prefixes
+
+| Prefix                    | Bump       | Example               |
+| ------------------------- | ---------- | --------------------- |
+| `[patch]` or `[fix]`      | patch      | `0.3.1` → `0.3.2`     |
+| `[minor]` or `[feat]`     | minor      | `0.3.1` → `0.4.0`     |
+| `[major]` or `[breaking]` | major      | `0.3.1` → `1.0.0`     |
+| _(none)_                  | no release | docs / CI / deps only |
+
+Example titles:
+
+- `[minor] Add public repository interfaces and subclassable adapter CRUD API`
+- `[patch] Fix mypy context manager typing for adapter subclasses`
+
+### Release notes
+
+Release notes are generated from commits since the previous tag (see [`scripts/ci/generate-release-notes.sh`](scripts/ci/generate-release-notes.sh)).
+
+### Manual release
+
+You can still push a `v*.*.*` tag manually; `publish.yml` will build and publish. The current baseline version is **0.3.1**.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-repositories"
-version = "0.1.0"
+version = "0.3.1"
 description = "Various python repository interfaces exposed as a python package."
 authors = [
     { name = "Brian Bjarke Jensen", email = "[email protected]" }

scripts/ci/bump-version.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "${SCRIPT_DIR}/common.sh"
+
+usage() {
+  echo "Usage: bump-version.sh <major|minor|patch>" >&2
+  echo "       bump-version.sh --from-tag <vX.Y.Z>" >&2
+  exit 1
+}
+
+if [[ $# -lt 1 ]]; then
+  usage
+fi
+
+if [[ "$1" == "--from-tag" ]]; then
+  if [[ $# -ne 2 ]]; then
+    usage
+  fi
+  VERSION="${2#v}"
+else
+  BUMP_TYPE="$1"
+  CURRENT=$(latest_tag_version)
+  VERSION=$(bump_semver "$CURRENT" "$BUMP_TYPE")
+fi
+
+set_pyproject_version "$VERSION"
+
+if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+  echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+else
+  echo "version=${VERSION}"
+fi
+
+echo "Updated pyproject.toml to version ${VERSION}" >&2

scripts/ci/check-pr-title.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "${SCRIPT_DIR}/common.sh"
+
+PR_TITLE="${1:-${PR_TITLE:-}}"
+
+if [[ -z "$PR_TITLE" ]]; then
+  echo "Usage: check-pr-title.sh <pr-title>  (changed files on stdin)" >&2
+  exit 1
+fi
+
+CHANGED_FILES=$(cat)
+
+if ! has_source_changes "$CHANGED_FILES"; then
+  echo "No changes under ${SOURCE_DIR}/ — PR title prefix not required."
+  exit 0
+fi
+
+if title_has_bump_prefix "$PR_TITLE"; then
+  echo "PR title has a valid version bump prefix."
+  exit 0
+fi
+
+cat >&2 <<EOF
+PR changes files under ${SOURCE_DIR}/ but the title lacks a version bump prefix.
+
+Title: ${PR_TITLE}
+
+When changing package source, start the PR title with one of:
+  [patch] or [fix]   — bug fix
+  [minor] or [feat]  — new feature
+  [major] or [breaking] — breaking change
+
+Example: [patch] Fix connection retry in RedisAdapter
+
+See .gitea/PULL_REQUEST_TEMPLATE.md for details.
+EOF
+exit 1

scripts/ci/common.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Shared helpers for release and PR title CI scripts.
+
+SOURCE_DIR="python_repositories"
+
+# Returns bump type (major|minor|patch) or empty if no valid prefix.
+bump_type_from_title() {
+  local title="$1"
+  local lower
+  lower=$(echo "$title" | tr '[:upper:]' '[:lower:]')
+
+  if echo "$lower" | grep -qE '^\[(major|breaking)\]'; then
+    echo "major"
+  elif echo "$lower" | grep -qE '^\[(minor|feat)\]'; then
+    echo "minor"
+  elif echo "$lower" | grep -qE '^\[(patch|fix)\]'; then
+    echo "patch"
+  fi
+}
+
+title_has_bump_prefix() {
+  [[ -n "$(bump_type_from_title "$1")" ]]
+}
+
+strip_bump_prefix() {
+  local title="$1"
+  echo "$title" | sed -E 's/^\[(patch|fix|minor|feat|major|breaking)\][[:space:]]*//i'
+}
+
+extract_pr_title_from_merge_commit() {
+  local msg="$1"
+  echo "$msg" | sed -n "s/^Merge pull request '\(.*\)' (#.*/\1/p"
+}
+
+changed_source_files() {
+  grep -E "^${SOURCE_DIR}/" || true
+}
+
+has_source_changes() {
+  local files="$1"
+  echo "$files" | changed_source_files | grep -q .
+}
+
+read_pyproject_version() {
+  sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1
+}
+
+latest_tag_version() {
+  local tag
+  tag=$(git describe --tags --abbrev=0 2>/dev/null || true)
+  if [[ -n "$tag" ]]; then
+    echo "${tag#v}"
+  else
+    read_pyproject_version
+  fi
+}
+
+set_pyproject_version() {
+  local version="$1"
+  sed -i.bak -E "s/^version = \".*\"/version = \"${version}\"/" pyproject.toml
+  rm -f pyproject.toml.bak
+}
+
+bump_semver() {
+  local current="$1"
+  local bump_type="$2"
+  local major minor patch
+
+  IFS=. read -r major minor patch <<< "$current"
+  case "$bump_type" in
+    major)
+      major=$((major + 1))
+      minor=0
+      patch=0
+      ;;
+    minor)
+      minor=$((minor + 1))
+      patch=0
+      ;;
+    patch)
+      patch=$((patch + 1))
+      ;;
+    *)
+      echo "Unknown bump type: $bump_type" >&2
+      return 1
+      ;;
+  esac
+  echo "${major}.${minor}.${patch}"
+}

scripts/ci/generate-release-notes.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "${SCRIPT_DIR}/common.sh"
+
+NEW_TAG="${1:-}"
+SUMMARY="${2:-}"
+PREV_TAG="${3:-}"
+
+if [[ -z "$NEW_TAG" ]]; then
+  echo "Usage: generate-release-notes.sh <new-tag> [summary] [prev-tag]" >&2
+  exit 1
+fi
+
+if [[ -z "$PREV_TAG" ]]; then
+  PREV_TAG=$(git describe --tags --abbrev=0 "${NEW_TAG}^" 2>/dev/null || git describe --tags --abbrev=0 2>/dev/null || true)
+fi
+
+NOTES="## Summary"
+if [[ -n "$SUMMARY" ]]; then
+  NOTES="${NOTES}
+
+$(strip_bump_prefix "$SUMMARY")"
+else
+  NOTES="${NOTES}
+
+Automated release ${NEW_TAG}."
+fi
+
+if [[ -n "$PREV_TAG" ]]; then
+  NOTES="${NOTES}
+
+## Changes since ${PREV_TAG}
+
+$(git log "${PREV_TAG}..HEAD" --pretty=format:'- %h %s' || true)"
+else
+  NOTES="${NOTES}
+
+## Changes
+
+$(git log --pretty=format:'- %h %s' -20 || true)"
+fi
+
+if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+  {
+    echo 'body<<EOF'
+    echo "$NOTES"
+    echo 'EOF'
+  } >> "$GITHUB_OUTPUT"
+else
+  echo "$NOTES"
+fi

scripts/ci/parse-merge-commit.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "${SCRIPT_DIR}/common.sh"
+
+COMMIT_MSG="${1:-${COMMIT_MSG:-}}"
+
+if [[ -z "$COMMIT_MSG" ]]; then
+  echo "Usage: parse-merge-commit.sh <commit-message>" >&2
+  exit 1
+fi
+
+PR_TITLE=$(extract_pr_title_from_merge_commit "$COMMIT_MSG")
+
+if [[ -z "$PR_TITLE" ]]; then
+  bump="skip"
+else
+  bump_type=$(bump_type_from_title "$PR_TITLE")
+  if [[ -n "$bump_type" ]]; then
+    bump="$bump_type"
+  else
+    bump="skip"
+  fi
+fi
+
+if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+  {
+    echo "pr_title=${PR_TITLE}"
+    echo "bump=${bump}"
+  } >> "$GITHUB_OUTPUT"
+else
+  echo "pr_title=${PR_TITLE}"
+  echo "bump=${bump}"
+fi