From 7ab0908fb3b214b9cab1a1e63ec2dcfcb8ce5be4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joachim=20L=C3=B8vgaard?= <joachim@loevgaard.dk>
Date: Mon, 17 Aug 2026 13:12:17 +0200
Subject: [PATCH] CI: add a Roave backwards-compatibility check on pull
 requests

Mirrors Setono/SyliusPluginSkeleton's workflow: compares the PR against its
base branch with roave/backward-compatibility-check and fails on BC breaks.
Runs on PHP 8.4 because the current tool releases require >= 8.4 (it analyses
our >= 8.1 sources fine); the checkout uses fetch-depth 0 so the base ref is
available. CLAUDE.md documents the gate.
---
 .../backwards-compatibility-check.yaml        | 35 +++++++++++++++++++
 CLAUDE.md                                     |  2 +-
 2 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/backwards-compatibility-check.yaml

diff --git a/.github/workflows/backwards-compatibility-check.yaml b/.github/workflows/backwards-compatibility-check.yaml
new file mode 100644
index 0000000..c6f24ac
--- /dev/null
+++ b/.github/workflows/backwards-compatibility-check.yaml
@@ -0,0 +1,35 @@
+# See https://github.com/Roave/BackwardCompatibilityCheck
+#
+# Compares the public API of the pull request against its base branch and fails on any breaking
+# change (removed/renamed symbols, narrowed parameter types, new required parameters, ...). This
+# package follows semver: BC breaks belong in the next major only — see UPGRADE.md.
+
+name: "Backwards Compatibility Check"
+
+on:
+    pull_request: ~
+
+jobs:
+    backwards-compatibility-check:
+        name: "Backwards Compatibility Check"
+
+        runs-on: "ubuntu-latest"
+
+        steps:
+            -   name: "Checkout"
+                uses: "actions/checkout@v6"
+                with:
+                    fetch-depth: 0
+
+            -   name: "Setup PHP, with composer and extensions"
+                uses: "shivammathur/setup-php@v2"
+                with:
+                    # The current tool releases require PHP >= 8.4; it analyses our >= 8.1 sources just fine.
+                    php-version: "8.4"
+                    coverage: "none"
+
+            -   name: "Install tool"
+                run: "composer global require roave/backward-compatibility-check"
+
+            -   name: "Check for BC breaks"
+                run: "~/.composer/vendor/bin/roave-backward-compatibility-check --from=origin/${{ github.event.pull_request.base.ref }} --format=github-actions"
diff --git a/CLAUDE.md b/CLAUDE.md
index d40f922..1fb9a8e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,7 +17,7 @@ Composer scripts (run via `composer <script>`):
 - `vendor/bin/infection` — mutation testing. Gates: `minMsi 50`, `minCoveredMsi 70`. The Stryker dashboard upload is branch-gated in `infection.json.dist` (`stryker.badge`) — currently `1.x`; update it when the working branch changes.
 - `composer e2e:smoke` / `e2e:listen` / `e2e:create` / `e2e:operate` — the dev-only end-to-end harness (`examples/e2e/`), documented in `examples/e2e/README.md`. It hits the **real** API, so it loads a gitignored `.env.local` (`QUICKPAY_API_KEY`, `QUICKPAY_PRIVATE_KEY`). `e2e:smoke` is the quickest real check (ping → create → link → get, charges nothing).
 
-CI (`.github/workflows/build.yaml`, branch `1.x`): coding-standards, dependency-analysis, static-analysis and unit-tests run PHP **8.1–8.5 × lowest/highest**; code-coverage (Codecov, `codecov/codecov-action@v5`) and mutation-tests (Stryker) run on 8.3. When changing dependency constraints, check both `lowest` and `highest` still resolve on 8.5.
+CI (`.github/workflows/build.yaml`, branch `1.x`): coding-standards, dependency-analysis, static-analysis and unit-tests run PHP **8.1–8.5 × lowest/highest**; code-coverage (Codecov, `codecov/codecov-action@v5`) and mutation-tests (Stryker) run on 8.3. `.github/workflows/backwards-compatibility-check.yaml` runs [Roave BC check](https://github.com/Roave/BackwardCompatibilityCheck) on every PR against its base branch (PHP 8.4, current tool) — a flagged break must either be reverted or be a deliberate, documented major-version change. When changing dependency constraints, check both `lowest` and `highest` still resolve on 8.5.
 
 ## Architecture