From ed400dbefe1354837e833cc4dfdffd1938f2872c Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:03:27 +0100
Subject: [PATCH 1/4] Add public API backward compatibility checks

---
 .github/workflows/backward-compatibility.yml | 45 ++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 .github/workflows/backward-compatibility.yml

diff --git a/.github/workflows/backward-compatibility.yml b/.github/workflows/backward-compatibility.yml
new file mode 100644
index 0000000..5d3e727
--- /dev/null
+++ b/.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

From 95263b88e6401303e5b4bb3eb659a1ff20c5abe0 Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:03:30 +0100
Subject: [PATCH 2/4] Document public API compatibility policy

---
 docs/backward-compatibility.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 docs/backward-compatibility.md

diff --git a/docs/backward-compatibility.md b/docs/backward-compatibility.md
new file mode 100644
index 0000000..1297018
--- /dev/null
+++ b/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.

From 9b2bf43f8989aacb70b8a1c87e843b180cbbb1bc Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:03:32 +0100
Subject: [PATCH 3/4] Add BC policy to documentation navigation

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index 78b2c1f..9ed1e9e 100644
--- a/mkdocs.yml
+++ b/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

From a7d8e5b753c297e5ed125b2314e3a7e06968a201 Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:03:35 +0100
Subject: [PATCH 4/4] Document automated backward compatibility checks

---
 CONTRIBUTING.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7ac022d..86aacd9 100644
--- a/CONTRIBUTING.md
+++ b/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.