Merge pull request #136 from abhi1693/ci/one-migration-per-pr

ci(policy): enforce one DB migration per PR

.github/workflows/ci.yml

@@ -62,6 +62,13 @@ jobs:
 
 
 
+      - name: Enforce one migration per PR
+        if: ${{ github.event_name == 'pull_request' }}
+        env:
+          GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          ./scripts/ci/one_migration_per_pr.sh
+
       - name: Run migration integrity gate
         if: ${{ github.event_name == 'pull_request' }}
         run: |

docs/policy/one-migration-per-pr.md

@@ -0,0 +1,23 @@
+# Policy: one DB migration per PR
+
+## Rule
+If a pull request adds migration files under:
+
+- `backend/migrations/versions/*.py`
+
+…then it must add **no more than one** migration file.
+
+## Why
+- Makes review and rollback simpler.
+- Reduces surprise Alembic multiple-head situations.
+- Keeps CI/installer failures easier to debug.
+
+## Common exceptions / guidance
+- If you have multiple Alembic heads, prefer creating **one** merge migration.
+- If changes are unrelated, split into multiple PRs.
+
+## CI enforcement
+CI runs `scripts/ci/one_migration_per_pr.sh` on PRs and fails if >1 migration file is added.
+
+## Notes
+This policy does not replace the existing migration integrity gate (`make backend-migration-check`). It is a lightweight guardrail to prevent multi-migration PRs.

scripts/ci/one_migration_per_pr.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Enforce: if a PR adds migration files under backend/migrations/versions/, it must add <= 1.
+# Rationale: keeps review/rollback straightforward and avoids surprise multiple-head merges.
+
+if [ "${GITHUB_EVENT_NAME:-}" != "pull_request" ]; then
+  echo "Not a pull_request event; skipping one-migration-per-PR gate."
+  exit 0
+fi
+
+BASE_SHA="${GITHUB_BASE_SHA:-${GITHUB_EVENT_PULL_REQUEST_BASE_SHA:-}}"
+HEAD_SHA="${GITHUB_SHA:-}"
+
+if [ -z "$BASE_SHA" ] || [ -z "$HEAD_SHA" ]; then
+  echo "Missing BASE_SHA/HEAD_SHA (BASE_SHA='$BASE_SHA', HEAD_SHA='$HEAD_SHA')"
+  exit 2
+fi
+
+# Ensure base is present in shallow clones.
+# NOTE: fetch may fail due to fetch-depth/ref settings; validate the commit exists after fetch.
+git fetch --no-tags --depth=1 origin "$BASE_SHA" || true
+if ! git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
+  echo "Base commit '$BASE_SHA' not found locally even after fetch. Check checkout fetch-depth / ref configuration."
+  exit 2
+fi
+
+# Only count *newly added* migration files. Modified/deleted migrations should not trip this gate.
+# See review thread: https://github.com/abhi1693/openclaw-mission-control/pull/136#discussion_r2807812935
+ADDED_FILES=$(git diff --name-only --diff-filter=A "$BASE_SHA" "$HEAD_SHA" || true)
+if [ -z "$ADDED_FILES" ]; then
+  echo "No added files detected."
+  exit 0
+fi
+
+# Be slightly strict: avoid counting non-migration python files (e.g. __init__.py).
+# Alembic versions typically look like: <hex_revision>_<slug>.py
+MIGRATIONS=$(echo "$ADDED_FILES" | grep -E '^backend/migrations/versions/[0-9a-f]+_.*\.py$' || true)
+COUNT=$(echo "$MIGRATIONS" | sed '/^$/d' | wc -l | tr -d ' ')
+
+if [ "$COUNT" -le 1 ]; then
+  echo "Migration gate OK (migrations_added=$COUNT)."
+  exit 0
+fi
+
+echo "Migration gate FAILED: this PR adds $COUNT migration files; policy allows at most 1."
+echo
+
+echo "Migrations detected:"
+echo "$MIGRATIONS"
+echo
+
+echo "How to fix:"
+echo "- Consolidate schema changes into a single migration file (squash)."
+echo "- If you have multiple Alembic heads, create ONE merge migration instead of several."
+echo "- If you truly need multiple migrations, split into multiple PRs."
+
+exit 1