roave/backward-compatibility-check

Tool to compare two revisions of a public API to check for BC breaks

Roave Backward Compatibility Check

, _(*1)

A tool that can be used to verify BC breaks between two versions of a PHP library., _(*2)

Pre-requisites/assumptions

• Your project uses git
• Your project uses composer.json to define its dependencies
• All source paths are covered by an "autoload" section in composer.json
• Changes need to be committed to git to be covered. You can implement your own logic to extract sources and dependencies from a project though.

Installation

composer require --dev roave/backward-compatibility-check

Install with Docker

You can also use Docker to run roave-backward-compatibility-check:, _(*3)

docker run --rm -v `pwd`:/app nyholm/roave-bc-check

Usage

Adding to a continuous integration pipeline

The typical intended usage is to just add roave-backward-compatibility-check to your CI build:, _(*4)

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., _(*5)

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., _(*6)

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:, _(*7)

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"

Nyholm Github Action

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:, _(*8)

.github/workflows/main.yml, _(*9)

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

Running manually

To generate additional documentation for changelogs:, _(*10)

vendor/bin/roave-backward-compatibility-check --format=markdown > results.md

GitHub Actions

When running in GitHub Actions, it is endorsed to use the --format=github-actions output format:, _(*11)

vendor/bin/roave-backward-compatibility-check --format=github-actions

Documentation

If you need further guidance:, _(*12)

vendor/bin/roave-backward-compatibility-check --help

Configuration

There are currently no configuration options available., _(*13)