Backward Compatibility Check Laravel Package

Product Decisions This Supports

• Enforce Semantic Versioning (SemVer) compliance: Automatically detect and block backward-incompatible (BC) changes in PHP/Laravel APIs, ensuring minor/patch releases adhere to SemVer principles.
• Shift-left quality gates: Integrate BC checks into CI/CD pipelines to fail builds early if API changes risk breaking downstream consumers (e.g., Laravel packages, SDKs, or third-party integrations).
• Build vs. buy: Avoid reinventing BC detection logic (e.g., custom scripts or manual reviews) by adopting a battle-tested, PHP-specific tool with Laravel ecosystem relevance.
• Roadmap prioritization:
  • Laravel package maintainers: Mandate BC checks for all public APIs in new/updated packages (e.g., spatie/laravel-*, laravel/breeze).
  • Enterprise PHP apps: Enforce BC compliance for internal libraries shared across microservices.
  • Open-source contributions: Require BC checks in PR templates or GitHub Actions for projects with >100 stars.
• Use cases:
  • API stability: Prevent breaking changes in Laravel’s core or popular packages (e.g., laravel/framework).
  • Migration safety: Validate BC compliance during major Laravel version upgrades (e.g., 9.x → 10.x).
  • Changelog automation: Generate markdown/JSON reports for changelogs (e.g., "BC: Removed User::findOrFail() in v10.0").

When to Consider This Package

• Adopt if:

  • Your project publishes public PHP APIs (Laravel packages, SDKs, or libraries) consumed by others.
  • You follow SemVer and want to automate BC validation in CI (reducing manual reviews).
  • Your team releases minor/patch versions frequently and needs to catch BC breaks early.
  • You use Git tags for versioning (SemVer-compliant, e.g., v1.2.3).
  • Your codebase is autoloaded via Composer (standard for Laravel/PHP projects).

• Look elsewhere if:

  • Your project is internal-only with no public APIs (BC checks are unnecessary).
  • You use non-SemVer versioning (e.g., date-based tags like 2023.1.0).
  • Your team prefers manual BC reviews or custom tools (e.g., PHPStan rules).
  • You’re not using PHP/Laravel (this tool is PHP-specific).
  • Your CI pipeline cannot fetch full Git history (e.g., shallow clones).

How to Pitch It (Stakeholders)

For Executives/Stakeholders:

*"This tool automates API compatibility checks in our CI pipeline, ensuring minor/patch releases never break downstream users—like Laravel packages or third-party integrations. By failing builds early when BC breaks occur, we:

• Reduce support costs from user-reported issues (e.g., 'Your package broke my app!').
• Accelerate releases by eliminating manual BC reviews for SemVer-compliant updates.
• Future-proof our ecosystem (e.g., Laravel packages) by enforcing API stability. Example: If we update spatie/laravel-permission, this tool would catch if we removed Permission::findByName() without a deprecation cycle, saving hours of bug triage. Cost: Zero—it’s a one-line CI addition. ROI: Fewer fire drills, happier users."*

For Engineering Teams:

*"Problem: Manual BC checks are error-prone, slow, and often skipped. Even small changes (e.g., adding a required param to a Laravel package’s method) can break hundreds of apps. Solution: roave/backward-compatibility-check is a PHP-native, Git-aware tool that:

• Scans your codebase against the last minor version (e.g., v1.2.0 → v1.3.0) to detect BC breaks.
• Integrates into CI (GitHub Actions, GitLab CI) in 5 minutes—just add a step.
• Supports Laravel: Works with Composer autoloading and Laravel’s public APIs (e.g., Illuminate\Support\Facades\*).
• Generates actionable output: Markdown for changelogs, GitHub Actions annotations, or JSON for custom dashboards. How we’ll use it:

1. Enforce for all public packages: Add to spatie/laravel-* and laravel/breeze CI pipelines.
2. Baseline false positives: Use .roave-backward-compatibility-check.xml to ignore intentional BC changes (e.g., deprecated methods).
3. Document BC changes: Auto-generate changelog sections like:

   BC Breaks:

   • User::findOrFail() removed (use firstOrFail()). Effort: Low (1–2 hours setup). Impact: Zero BC breakouts in minor releases."*