:ab: Tool to compare two revisions of a class API to check for BC breaks
:ab: Tool to compare two revisions of a class API to check for BC breaks
A tool that can be used to verify BC breaks between two versions of a PHP library.
[!TIP] Enjoy checking your API compatibility :) if you need help with this tool, auditing your code, or support on your legacy applications, feel free to get in touch.
- The Roave Team
gitcomposer.json to define its dependencies"autoload" section in composer.jsongit to be covered. You can implement your own logic to extract sources and dependencies from a project though.composer require --dev roave/backward-compatibility-checkYou can also use Docker to run roave-backward-compatibility-check:
docker run --rm -v `pwd`:/app nyholm/roave-bc-checkThe typical intended usage is to just add roave-backward-compatibility-check
to your CI build:
vendor/bin/roave-backward-compatibility-checkThis will automatically detect the last minor version tagged, and
compare the API against the current HEAD. If any BC breaks are found,
the tool returns a non-zero status, which on most CI systems will cause
the build to fail.
NOTE: detecting the base version only works if you have git tags in
the SemVer-compliant x.y.z format, such as 1.2.3.
NOTE: since this tool relies on tags, you need to make sure tags are fetched
as part of your CI pipeline. For example in a GitHub action, note the use of
fetch-depth: 0:
jobs:
roave-backwards-compatibility-check:
name: Roave Backwards Compatibility Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: "Install PHP"
uses: shivammathur/setup-php@v2
with:
php-version: "8.0"
- name: "Install dependencies"
run: "composer install"
- name: "Check for BC breaks"
run: "vendor/bin/roave-backward-compatibility-check"Tobias Nyholm also offers a simple GitHub action that you can use in your Github pipeline. We recommend this for most cases as it is simple to set up:
.github/workflows/main.yml:
on: [push]
name: Test
jobs:
roave-backwards-compatibility-check:
name: Roave Backwards Compatibility Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: "Check for BC breaks"
uses: docker://nyholm/roave-bc-check-gaTo generate additional documentation for changelogs:
vendor/bin/roave-backward-compatibility-check --format=markdown > results.mdWhen running in GitHub Actions, it is endorsed to use the --format=github-actions output format:
vendor/bin/roave-backward-compatibility-check --format=github-actionsIf you need further guidance:
vendor/bin/roave-backward-compatibility-check --helpThe file .roave-backward-compatibility-check.xml is read from the current working directory (when it exists) and sets configuration for the command.
It's expected to be an XML file that follows our schema:
Example:
#\[BC\] CHANGED: The parameter \$a of TestArtifact\\TheClass\#method\(\)#
#\[BC\] CHANGED: The parameter \$b of TestArtifact\\TheClass\#method2\(\)#
No open issues yet, or sync has not completed.