From 6df14e2c00ce11fd24bd3ba85c180791b436d32f Mon Sep 17 00:00:00 2001
From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com>
Date: Tue, 21 Apr 2026 21:22:35 +0100
Subject: [PATCH] Enforce v1beta1 API stability

Flip the advisory CRD Schema Compatibility check (added in #4980 and
repaired in #4987) into an enforcing check, and document the contract.

Three pieces:

1. Workflow: drop continue-on-error, add an if: guard on the job that
   skips the check when the api-break-allowed label is applied. A
   skipped required-check counts as passing for branch protection, so
   the label is the only path through for an intentional break. Update
   the header comment and step summary heading to drop the "Phase 1:
   advisory" framing.

2. CONTRIBUTING.md: add a new "API Stability" top-level section with
   the v1beta1 stability contract (no field removal, type change,
   new required fields, validation narrowing, finalizer rename,
   spec.scope flip, un-serving a served version). Separate subsection
   documents the api-break-allowed escape hatch and the
   maintainer-coordination expectations.

3. PR template: add an "API Compatibility" section after Test plan
   that prompts contributors to describe the break + migration path
   when the label is applied. Section is standing (GitHub templates
   don't support conditional rendering) but the wording makes the
   N/A-for-non-breaking-PRs case explicit via the checkbox.

Post-merge maintainer actions (not code, can't be automated from a
PR): create the api-break-allowed GitHub label, and add "CRD Schema
Compatibility" to the required status checks in branch protection
for main.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/pull_request_template.md | 19 ++++++++++++++++
 .github/workflows/api-compat.yml | 18 +++++++++------
 CONTRIBUTING.md                  | 38 ++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 8fe497db20..8a69e2dc01 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -42,6 +42,25 @@ describe exactly what you tested below the checkbox.
 - [ ] Linting (`task lint-fix`)
 - [ ] Manual testing (describe below)
 
+## API Compatibility
+
+<!--
+The CRD Schema Compatibility check guards the v1beta1 operator API.
+If the check flags this PR as Incompatible and the break is intentional,
+apply the `api-break-allowed` label and describe below:
+
+1. Which fields, types, or CRDs are changing.
+2. Why the break is unavoidable.
+3. The user-facing migration path (what cluster admins need to do).
+
+See CONTRIBUTING.md → "API Stability" for the full rubric. Coordinate
+with maintainers before applying the label.
+
+Remove this section entirely if the PR does not touch operator API surface.
+-->
+
+- [ ] This PR does not break the `v1beta1` API, OR the `api-break-allowed` label is applied and the migration guidance is described above.
+
 ## Changes
 
 <!--
diff --git a/.github/workflows/api-compat.yml b/.github/workflows/api-compat.yml
index 0f4b112d5b..e9a5341bbb 100644
--- a/.github/workflows/api-compat.yml
+++ b/.github/workflows/api-compat.yml
@@ -2,10 +2,11 @@ name: API Compatibility
 
 # This workflow guards the stability of the v1beta1 operator API surface.
 #
-# Phase 1 (current): advisory only. `crd-schema-check` runs with
-# continue-on-error: true so breaking-change findings are surfaced via the
-# job's step summary but do not block merges. Remove continue-on-error in
-# Phase 2 to start enforcing.
+# A breaking CRD schema change (field removal, type change, required-field
+# addition, etc.) fails this check and blocks the PR. If the break is
+# intentional — almost exclusively for graduation to v1beta2 — apply the
+# `api-break-allowed` label to skip the check. See CONTRIBUTING.md → "API
+# Stability" for the full rubric.
 
 on:
   pull_request:
@@ -28,8 +29,11 @@ jobs:
   crd-schema-check:
     name: CRD Schema Compatibility
     runs-on: ubuntu-latest
-    # Phase 1: advisory only. Remove in Phase 2 to enforce.
-    continue-on-error: true
+    # Skip the check entirely when `api-break-allowed` is applied — a
+    # required check that is skipped (rather than failed) counts as passing
+    # for branch protection, so this is the escape hatch for intentional
+    # breaks. Do not remove the label guard without a replacement path.
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'api-break-allowed') }}
     # Expected runtime is ~1 minute (checkout + go setup + git fetch tag +
     # go install + per-CRD checker loop). 10 minutes is a cheap upper
     # bound that protects against a hung go install or git fetch.
@@ -146,7 +150,7 @@ jobs:
           fi
 
           {
-            echo "## API Compatibility — CRD Schema Check (Phase 1: advisory)"
+            echo "## API Compatibility — CRD Schema Check"
             echo ""
             echo "**Baseline**: $BASELINE_TAG"
             echo "**Status**: $STATUS"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8789d92c4e..9b663150f3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -148,3 +148,41 @@ We follow the commit formatting recommendations found on
 1. Do not end the subject line with a period
 1. Use the imperative mood in the subject line
 1. Use the body to explain what and why vs. how
+
+## API Stability
+
+The `v1beta1` operator API is stable. CRD schemas and Go types under
+`cmd/thv-operator/api/v1beta1/` carry a compatibility commitment to users
+running the published operator chart. Contributors must not:
+
+- Remove or rename any field, type, or CRD kind in `v1beta1`.
+- Change a field's Go type, JSON tag, or OpenAPI schema type.
+- Add new required fields to existing types.
+- Narrow validation rules (smaller `maxLength`, stricter `pattern`, fewer
+  `enum` values).
+- Rename a finalizer or change a CRD `shortName`.
+- Flip a CRD's `spec.scope` between `Namespaced` and `Cluster`.
+- Un-serve a currently-served version without a deprecation-cycle release.
+
+New fields must be optional. New behaviour must be opt-in via new fields.
+The `CRD Schema Compatibility` CI check enforces the CRD side of this
+contract against the last published release tag on every PR that touches
+`cmd/thv-operator/api/**` or `deploy/charts/operator-crds/files/crds/**`.
+
+### The `api-break-allowed` escape hatch
+
+If you have a genuine reason to break the API — the main expected use
+case is graduation to `v1beta2` — apply the `api-break-allowed` label to
+the PR. This skips the compatibility check.
+
+Before applying the label:
+
+1. **Coordinate with maintainers first.** Open a Discord thread or an
+   issue describing what you are breaking and why.
+2. **Describe the break in the PR description.** Spell out which API
+   elements are changing, what clusters need to do to migrate, and whether
+   downstream consumers (CLI, chart users, operator integrations) need
+   coordinated releases.
+3. **Do not use the label to silence a false positive.** If the check
+   fires on a change you believe is non-breaking, file a bug against the
+   workflow — silencing it hides real breaks on subsequent PRs.