Mutation testing badge Type Coverage Latest Stable Version License
A tool that can be used to verify BC breaks between two versions of a PHP library.
- Your project uses
git - Your project uses
composer.jsonto define its dependencies - All source paths are covered by an
"autoload"section incomposer.json - Changes need to be committed to
gitto be covered. You can implement your own logic to extract sources and dependencies from a project though.
composer require --dev roave/backward-compatibility-check
You 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-check
This 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-ga
To 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-actions
If you need further guidance:
vendor/bin/roave-backward-compatibility-check --help
The 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:
<?xml version="1.0" encoding="UTF-8" ?> <roave-bc-check xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vendor/roave/backward-compatibility-check/resources/schema.xsd"> <baseline> <ignored-regex>#\[BC\] CHANGED: The parameter \$a of of TestArtifact\\TheClass\#method\(\)#</ignored-regex> <ignored-regex>#\[BC\] CHANGED: The parameter \$b of of TestArtifact\\TheClass\#method2\(\)#</ignored-regex> </baseline> </roave-bc-check>