Add backwards-compatibility sub-action wrapping Roave's BC check

Wraps roave/backward-compatibility-check with --format=github-actions
so PR violations show up as inline annotations. Inputs: php-version
(default 8.2), extensions, from (default origin/<PR base ref>).

Wired into the root action with an if: github.event_name ==
'pull_request' guard, so root consumers don't break on non-PR
triggers. Standalone consumers scope their workflow to pull_request
or pass an explicit from ref.

Author: loevgaard

README.md

@@ -14,18 +14,19 @@ composer require --dev setono/sylius-plugin
 
 This repository also ships a suite of composite GitHub Actions that implement the Setono Sylius plugin CI pipeline. Each check is its own sub-action, addressable as `setono/sylius-plugin/<name>@<ref>`, so consumers can run each in its own job with its own matrix. There is also a root action `setono/sylius-plugin@<ref>` listed on the GitHub Marketplace that runs all checks sequentially in one job — handy for trying it out, slow for real CI.
 
-Eight actions ship in this repository:
+Nine actions ship in this repository:
 
 | Action | Purpose |
 |---|---|
-| `setono/sylius-plugin@<ref>` | Root action. Runs all seven checks sequentially in one job |
+| `setono/sylius-plugin@<ref>` | Root action. Runs all eight checks sequentially in one job |
 | `setono/sylius-plugin/coding-standards@<ref>` | composer validate, normalize, check-style, rector dry-run, yaml/twig lint |
 | `setono/sylius-plugin/dependency-analysis@<ref>` | composer-dependency-analyser against production deps |
 | `setono/sylius-plugin/static-code-analysis@<ref>` | `vendor/bin/phpstan analyse`, with `sylius/sylius` removed first |
 | `setono/sylius-plugin/unit-tests@<ref>` | `vendor/bin/phpunit` |
 | `setono/sylius-plugin/integration-tests@<ref>` | MySQL + Doctrine schema validation against `tests/Application` |
 | `setono/sylius-plugin/mutation-tests@<ref>` | Infection, with optional Stryker Dashboard reporting |
 | `setono/sylius-plugin/code-coverage@<ref>` | PHPUnit with pcov, upload to Codecov |
+| `setono/sylius-plugin/backwards-compatibility@<ref>` | Roave backward-compatibility-check against the PR base ref |
 
 Pin the floating major (`@v2`) for automatic patch updates, or pin a specific tag (`@2.1.0`) for full reproducibility. Note the asymmetry: exact tags are bare-numeric (composer convention), the floating major uses the `v` prefix (action ecosystem convention).
 
@@ -212,6 +213,31 @@ jobs:
                     codecov-token: "${{ secrets.CODECOV_TOKEN }}"
 ```
 
+#### `backwards-compatibility`
+
+Wraps [Roave's `backward-compatibility-check`](https://github.com/Roave/BackwardCompatibilityCheck). Compares the PR's diff against its base ref and fails on any public-API break. Inline annotations show up directly on the changed lines via `--format=github-actions`.
+
+| Input | Default | Description |
+|---|---|---|
+| `php-version` | `8.2` | PHP version to install |
+| `extensions` | `intl, mbstring` | PHP extensions to install |
+| `from` | `origin/${{ github.event.pull_request.base.ref }}` | Git ref to compare against. The default only resolves on `pull_request` triggers — pass an explicit ref for other triggers |
+
+The root action invokes this sub-action only on `pull_request` triggers (gated via `if:`), so it's safe to consume the root from any workflow. When invoking this sub-action standalone, scope the workflow to `on: pull_request` (or pass an explicit `from` ref).
+
+```yaml
+name: "Backwards compatibility"
+
+on:
+    pull_request: ~
+
+jobs:
+    backwards-compatibility:
+        runs-on: "ubuntu-latest"
+        steps:
+            -   uses: "setono/sylius-plugin/backwards-compatibility@v2"
+```
+
 ### Root action
 
 The root action runs all seven sub-actions sequentially in a single job. **It is roughly five times slower than running the same checks as parallel jobs using the sub-actions**, because each sub-action repeats checkout + PHP setup + composer install. The root exists for the GitHub Marketplace listing and as a quick way to try the suite; for real CI, use the sub-actions in parallel jobs.

action.yml

@@ -92,3 +92,9 @@ runs:
                 dependencies: "${{ inputs.dependencies }}"
                 extensions: "${{ inputs.extensions }}"
                 codecov-token: "${{ inputs.codecov-token }}"
+
+        -   if: "github.event_name == 'pull_request'"
+            uses: "setono/sylius-plugin/backwards-compatibility@v2"
+            with:
+                php-version: "${{ inputs.php-version }}"
+                extensions: "${{ inputs.extensions }}"

backwards-compatibility/action.yml

@@ -0,0 +1,35 @@
+name: "Backwards compatibility"
+description: "Run Roave's backward-compatibility-check against the pull request's base ref"
+
+inputs:
+    php-version:
+        description: "PHP version to install"
+        required: false
+        default: "8.2"
+    extensions:
+        description: "PHP extensions to install"
+        required: false
+        default: "intl, mbstring"
+    from:
+        description: "Git ref to compare against. The default works only in pull_request triggers; pass an explicit ref otherwise."
+        required: false
+        default: "origin/${{ github.event.pull_request.base.ref }}"
+
+runs:
+    using: "composite"
+    steps:
+        -   uses: "actions/checkout@v6"
+            with:
+                fetch-depth: 0
+
+        -   uses: "shivammathur/setup-php@v2"
+            with:
+                php-version: "${{ inputs.php-version }}"
+                extensions: "${{ inputs.extensions }}"
+                coverage: "none"
+
+        -   shell: "bash"
+            run: "composer global require roave/backward-compatibility-check"
+
+        -   shell: "bash"
+            run: "~/.composer/vendor/bin/roave-backward-compatibility-check --from=${{ inputs.from }} --format=github-actions"

openspec/specs/ci-composite-actions/spec.md

@@ -3,18 +3,19 @@
 ## Purpose
 TBD - created by archiving change add-ci-composite-actions. Update Purpose after archive.
 ## Requirements
-### Requirement: Repository ships seven independently invokable composite GitHub Actions
+### Requirement: Repository ships eight independently invokable composite GitHub Actions
 
-The repository SHALL provide seven composite GitHub Actions, each in its own subdirectory at the repo root with an `action.yml` file. Each sub-action MUST be invokable in a consumer workflow as `setono/sylius-plugin/<sub-action-name>@<ref>` and MUST be self-contained (it MUST NOT depend on any other sub-action in this repo).
+The repository SHALL provide eight composite GitHub Actions, each in its own subdirectory at the repo root with an `action.yml` file. Each sub-action MUST be invokable in a consumer workflow as `setono/sylius-plugin/<sub-action-name>@<ref>` and MUST be self-contained (it MUST NOT depend on any other sub-action in this repo).
 
-The seven sub-actions are:
+The eight sub-actions are:
 - `coding-standards`
 - `dependency-analysis`
 - `static-code-analysis`
 - `unit-tests`
 - `integration-tests`
 - `mutation-tests`
 - `code-coverage`
+- `backwards-compatibility`
 
 #### Scenario: Consumer invokes a single sub-action
 
@@ -120,6 +121,27 @@ The `code-coverage` sub-action SHALL install composer dependencies, run `vendor/
 - **WHEN** the action is invoked with a valid `codecov-token`
 - **THEN** clover coverage is generated and uploaded to Codecov successfully
 
+### Requirement: Backwards compatibility sub-action runs Roave's backward-compatibility-check against the PR base ref
+
+The `backwards-compatibility` sub-action SHALL check out the consumer's repo with `fetch-depth: 0`, install PHP, install `roave/backward-compatibility-check` via `composer global require`, then run `~/.composer/vendor/bin/roave-backward-compatibility-check --from=<from> --format=github-actions`. It SHALL accept inputs `php-version` (default `8.2`), `extensions` (default `intl, mbstring`), and `from` (default `origin/${{ github.event.pull_request.base.ref }}`).
+
+The sub-action itself does not gate on event type. The root action MUST gate its invocation of `backwards-compatibility` with `if: github.event_name == 'pull_request'`, so the root remains safe to consume from any workflow. Standalone consumers SHALL scope their workflow to `on: pull_request` or pass an explicit `from` ref.
+
+#### Scenario: PR-triggered invocation against the base ref
+
+- **WHEN** the action is invoked from a `pull_request`-triggered workflow with no `from` input
+- **THEN** the BC check runs against `origin/<base-ref>` and any public-API regression is reported as a GitHub Actions inline annotation on the offending source line
+
+#### Scenario: Consumer overrides the comparison ref
+
+- **WHEN** the action is invoked with an explicit `from` input (e.g., `from: 'origin/main'`)
+- **THEN** the BC check runs against the provided ref instead of the PR base ref, allowing the action to work outside `pull_request` triggers
+
+#### Scenario: Root action skips backwards-compatibility on non-PR triggers
+
+- **WHEN** the root action is invoked from a non-`pull_request` trigger
+- **THEN** the root's `if: github.event_name == 'pull_request'` guard skips the backwards-compatibility step entirely, so non-PR runs of the root succeed regardless of the BC sub-action's PR requirement
+
 ### Requirement: All actions follow GitHub composite-action constraints
 
 Every `run:` step in every action SHALL declare `shell: bash`. No action SHALL declare a top-level `env:` block (composite actions don't support it). Environment variables that need to span multiple steps SHALL be set per-step via `env:` on each `run:` step that needs them.
@@ -140,7 +162,7 @@ Action releases SHALL reuse the repository's existing tag scheme (e.g., `2.0.0`,
 
 ### Requirement: README documents every sub-action and its inputs
 
-`README.md` SHALL contain a section documenting each of the seven sub-actions and the root action: action reference path, all inputs (with defaults and descriptions), and at least one consumer usage example. Per the project's existing rule, no new feature is considered complete until the README reflects it.
+`README.md` SHALL contain a section documenting each of the eight sub-actions and the root action: action reference path, all inputs (with defaults and descriptions), and at least one consumer usage example. Per the project's existing rule, no new feature is considered complete until the README reflects it.
 
 #### Scenario: Consumer reads README to learn how to invoke the actions