Backward Compatibility Check Laravel Package

Product Decisions This Supports

• Enforcing Semantic Versioning (SemVer) Compliance: Automatically validate backward compatibility (BC) breaks between minor releases, ensuring adherence to SemVer principles (e.g., no BC breaks in minor versions). This aligns with roadmap items targeting stability, API contracts, or enterprise-grade reliability.
• Shift-Left Quality: Integrate BC checks into CI/CD pipelines to catch API regressions early, reducing costly post-release fixes. Prioritize for teams adopting GitHub Actions, GitLab CI, or Jenkins.
• Build vs. Buy: Avoid reinventing BC detection logic (e.g., custom scripts or manual reviews). Justify adoption by comparing effort to maintain in-house solutions vs. this MIT-licensed, actively maintained tool.
• Use Cases:
  • Library/API Development: Critical for open-source or internal SDKs where downstream consumers rely on stability.
  • Legacy Modernization: Audit deprecated APIs or refactorings to ensure compatibility with existing integrations.
  • Compliance: Meet internal policies or client SLAs requiring BC guarantees (e.g., financial systems, healthcare).
  • Changelog Automation: Generate machine-readable BC reports for changelogs (e.g., --format=markdown or --format=github-actions).

When to Consider This Package

• Adopt if:

  • Your project uses PHP/Laravel and follows SemVer (or needs to).
  • You release minor versions and must guarantee BC (e.g., 1.2.0 → 1.3.0).
  • Your team lacks manual BC review processes or relies on ad-hoc checks.
  • You use Git for versioning and Composer for dependencies.
  • Stakeholders demand automated compliance (e.g., DevOps, QA, or executives).

• Look Elsewhere if:

  • Your project uses non-PHP languages (e.g., JavaScript, Python).
  • You don’t tag releases (tool requires SemVer-compliant tags like v1.2.3).
  • Your BC breaks are intentional (e.g., major versions) and documented separately.
  • You need runtime BC checks (this tool analyzes code statically, not at runtime).
  • Your team prefers custom solutions (e.g., existing PHPStan rules or Psalm plugins) over third-party tools.

How to Pitch It (Stakeholders)

For Executives: "This tool automates backward compatibility checks in our PHP/Laravel codebase, ensuring minor releases don’t break existing integrations—saving time and reducing risk. By integrating it into CI, we’ll catch API regressions early, just like we do for unit tests. It’s a lightweight, open-source solution used by teams at Roave, with negligible overhead. For a one-time setup, it pays dividends in stability and developer confidence."

For Engineering: *"Roave’s BC Check is a zero-configuration way to enforce SemVer in PHP. It:

• Fails CI if a minor release introduces BC breaks (e.g., removed methods, changed parameter types).
• Supports GitHub Actions out-of-the-box (see Nyholm’s action).
• Ignores intentional changes via .roave-backward-compatibility-check.xml (e.g., for deprecations).
• Works with PHP 8.0–8.5 and modern tooling (Composer, Git). Example: Add to composer.json as a dev dependency, run in CI, and let it block bad merges. 5 minutes to set up, infinite ROI in stability."*

For QA/DevOps: *"This replaces manual BC audits with automated, reproducible checks. Key benefits:

• No false positives: Uses PHP’s parser to detect actual API changes (e.g., protected → private in final classes is not a BC break).
• CI-friendly: Returns non-zero exit codes on failures, integrates with Slack/email alerts via --format=github-actions.
• Changelog-ready: Outputs markdown/JSON for automated release notes (e.g., ‘BC: Removed User::legacyMethod()’). Ask PMs to prioritize this for any project shipping minor releases to external consumers."