Add automated public API backward compatibility checks

.github/workflows/backward-compatibility.yml

@@ -0,0 +1,45 @@
+name: Backward Compatibility
+
+on:
+  pull_request:
+    paths:
+      - "src/**"
+      - "composer.json"
+      - ".github/workflows/backward-compatibility.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  backwards-compatibility:
+    runs-on: ubuntu-latest
+    name: Public API BC check
+
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          extensions: dom, libxml, simplexml, zip
+          coverage: none
+
+      - name: Install Roave BC Check
+        run: |
+          composer global require \
+            roave/backward-compatibility-check:8.22.0 \
+            --no-interaction \
+            --no-progress
+
+      - name: Check public API compatibility with main
+        run: |
+          BC_BIN="$(composer global config bin-dir --absolute)/roave-backward-compatibility-check"
+          "$BC_BIN" \
+            --from=origin/main \
+            --to=HEAD \
+            --format=github-actions

CONTRIBUTING.md

@@ -19,6 +19,7 @@ The supported PHP matrix is 8.0 through 8.5. CI must remain green on all support
 - Create a focused branch from `main`.
 - Add or update tests for behavior changes.
 - Keep public API changes additive unless a breaking change is explicitly planned for a major release.
+- Public API changes are checked automatically against `origin/main` with Roave Backward Compatibility Check.
 - Update README/API/cookbook documentation when public behavior changes.
 - Keep coverage at or above the configured 90% project and patch thresholds.
 - Use English for source code, comments, commit messages and pull-request descriptions.

docs/backward-compatibility.md

@@ -0,0 +1,21 @@
+# Backward compatibility
+
+The library treats its documented public PHP API as a Semantic Versioning contract.
+
+Pull requests that modify `src/` or Composer metadata run Roave Backward Compatibility Check against:
+
+```text
+origin/main -> pull request HEAD
+```
+
+The check detects incompatible public API changes such as removed symbols, incompatible method signatures and other contract changes in Composer-autoloaded source.
+
+## Intentional breaking changes
+
+Breaking changes should be reserved for a planned major release. If a break is intentional:
+
+1. document it in `CHANGELOG.md` and `UPGRADING.md`;
+2. provide a migration path where practical;
+3. update the BC workflow/baseline only as part of the explicitly reviewed major-version work.
+
+The BC tool is installed only in its dedicated PHP 8.4 CI job so it does not constrain the package's PHP 8.0 runtime compatibility.

mkdocs.yml

@@ -60,6 +60,7 @@ nav:
       - Validation: validation.md
       - Security: security.md
       - Release Supply Chain: supply-chain.md
+      - Backward Compatibility: backward-compatibility.md
       - iDevices: idevices.md
       - Assets and Package Entries: assets.md
       - Performance: performance.md