Backward Compatibility Check Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Add to require-dev in composer.json for CI-only usage.

2. First Run:

   vendor/bin/roave-backward-compatibility-check
   

   • Automatically compares HEAD against the last minor Git tag (e.g., v1.2.0 → v1.3.0).
   • Fails CI if BC breaks are detected (non-zero exit code).

3. Prerequisites Check:

   • Ensure composer.json has "autoload" sections for all source paths.
   • Verify Git tags follow SemVer (e.g., v1.2.3).
   • Fetch all tags in CI (e.g., GitHub Actions: fetch-depth: 0).

First Use Case: CI Integration

Example GitHub Actions Workflow (.github/workflows/bc-check.yml):

name: BC Check
on: [push, pull_request]

jobs:
  bc-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Critical: Fetches all tags
      - run: composer install
      - run: vendor/bin/roave-backward-compatibility-check

Key Flags for Output:

Implementation Patterns

Workflow: Feature Development

1. Tagging Strategy:

   • Tag releases as vX.Y.Z (e.g., v1.2.0).
   • Use minor tags for BC-breaking changes (e.g., v2.0.0).

2. Daily Workflow:

   • Run BC checks before merging to main/develop:

     git checkout feature-branch
     vendor/bin/roave-backward-compatibility-check --baseline=origin/main
     

   • Fix issues before pushing to shared branches.

3. Integration with Tests:

   • Add to composer.json scripts:

     "scripts": {
       "test": [
         "@phpunit",
         "@roave-bc-check"
       ],
       "roave-bc-check": "roave-backward-compatibility-check"
     }
     

   • Run with composer test in CI.

Advanced Patterns

1. Custom Baseline Comparison

Compare against a specific tag (e.g., v1.5.0):

vendor/bin/roave-backward-compatibility-check --baseline=v1.5.0

2. Ignoring Known BC Breaks

Create .roave-backward-compatibility-check.xml:

<roave-bc-check>
    <baseline>
        <ignored-regex>#\[BC\] CHANGED: Parameter \$param of MyClass\#method\(\)#</ignored-regex>
    </baseline>
</roave-bc-check>

• Use regex to whitelist intentional BC breaks (e.g., deprecated methods).

3. Output Customization

Generate JSON for programmatic use:

vendor/bin/roave-backward-compatibility-check --format=json > bc-results.json

• Parse results to auto-generate changelogs or block merges via scripts.

4. Dockerized CI

Use the official image for zero setup:

steps:
  - uses: docker://nyholm/roave-bc-check-ga

Gotchas and Tips

Pitfalls

1. False Positives:

   • Symfony/Doctrine Changes: The tool may flag changes in vendor classes (e.g., symfony/console). Exclude them via:

     vendor/bin/roave-backward-compatibility-check --exclude-dir=vendor/
     

   • Final Classes: Changing protected → private in a final class is not a BC break (fixed in v8.18.0).

2. Git Tag Issues:

   • No Tags: The tool fails silently. Ensure tags exist:

     git tag -a v1.0.0 -m "Initial release"
     git push --tags
     

   • Shallow Clones: fetch-depth: 0 is mandatory in CI.

3. PHP Version Mismatches:

   • The tool supports PHP 8.0–8.5 (as of v8.20.0). Ensure your CI environment matches.

Debugging Tips

1. Verbose Output:

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

   • Shows detailed diffs for each BC break.

2. Dry Run:

   vendor/bin/roave-backward-compatibility-check --dry-run
   

   • Lists issues without failing the build.

3. Schema Validation:

   • If .roave-backward-compatibility-check.xml fails, validate against:

     vendor/roave/backward-compatibility-check/Resources/schema.xsd
     

Extension Points

1. Custom Formatters:

   • Extend the tool by implementing Roave\BackwardCompatibility\Formatter\FormatterInterface.
   • Example: Add a Slack notification formatter.

2. Pre-Commit Hooks:

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

   Add to .git/hooks/pre-commit:

   #!/bin/sh
   vendor/bin/roave-backward-compatibility-check --baseline=HEAD~1
   

3. Laravel-Specific Tips:

   • Exclude Config/Cache:

     vendor/bin/roave-backward-compatibility-check --exclude-dir=bootstrap/cache
     

   • Focus on App/Classes:

     vendor/bin/roave-backward-compatibility-check --autoload-file=vendor/composer/autoload_psr4.php
     

Pro Tips

1. Changelog Automation: Pipe output to a script that auto-updates CHANGELOG.md:

   vendor/bin/roave-backward-compatibility-check --format=markdown | ./scripts/update-changelog.sh
   

2. Team Onboarding:

   • Add a CI badge to README.md:
   • Document the .roave-backward-compatibility-check.xml file in CONTRIBUTING.md.

3. Performance:

   • Cache results in CI (e.g., GitHub Actions cache):

     - name: Cache BC Check
       uses: actions/cache@v3
       with:
         path: ~/.cache/roave-bc-check
         key: ${{ runner.os }}-bc-check-${{ hashFiles('**/composer.lock') }}