Backward Compatibility Check Laravel Package

Product Decisions This Supports

• Deciding whether our public PHP surface is a product commitment. If we publish packages (Laravel packages on Packagist, SDKs, or shared internal libraries with multiple consuming teams), this tool turns "we try to follow SemVer" from an aspiration into an enforced gate. That is a product-level decision about how much of our API we promise to keep stable, and what a major version bump means to customers.
• Release/roadmap scoping: minor vs. major. The tool compares the last SemVer tag against HEAD and fails the build on any BC break, which forces an explicit decision on every change: ship it as a patch/minor, or accept a major version and the migration guide, deprecation cycle, and comms work that come with it. This is exactly the roadmap tradeoff a PM should be making consciously rather than discovering after a customer's upgrade breaks.
• Support-cost and escalation forecasting. Every undetected BC break converts into a support ticket, a hotfix, or a "we can't upgrade" blocker for a consuming team. A BC gate is a cheap, deterministic way to buy down that downstream cost — arguably a better ROI than a fourth QA environment.
• Build vs. buy vs. skip. 603 stars, MIT, actively released, but effectively zero dependents recorded — this is a well-known niche tool, not a widely adopted ecosystem standard. Build-vs-buy here is really "adopt a focused single-purpose CLI" vs. "write our own reflection-diff scripts" (weeks of effort, worse coverage) vs. "rely on code review discipline" (free, unreliable). The honest answer is: adopt, but treat it as one gate among several, not a substitute for API review.
• Feature-level use cases worth planning around:
  • Public package releases where the consumer is outside our deploy boundary and can't be coordinated.
  • Internal platform libraries where a break means N teams each spend a day upgrading — the cost is diffuse but real, and this makes it visible at PR time.
  • Auto-generating changelog evidence: the --format=markdown output produces a "what changed in the API" section for release notes, which removes a recurring manual chore.
  • Complements, doesn't replace, static analysis and test suites — it detects signature/visibility/enum-case/added-parameter breaks, not behavioral or semantic ones.
• What it cannot decide for us. It has no opinion on whether a break is acceptable. Baseline ignore regexes are a real governance lever: an allowlist of tolerated breaks will drift and quietly become "we ignore BC checks." A PM should insist that baseline entries carry a ticket and a removal date, or the gate becomes theater.

When to Consider This Package

Adopt when:

• We publish at least one Composer package with external or cross-team consumers, and its version numbers mean something to someone.
• The repo is on git, uses composer.json, and all source paths are covered by an "autoload" section — the README is explicit about these preconditions, and failing them silently degrades results.
• CI can fetch full history and tags (fetch-depth: 0); the default shallow checkout breaks the "detect last minor tag" heuristic.
• Releases are SemVer-tagged in x.y.z form. Without compliant tags there is no base version to compare against and the tool mostly does nothing useful.
• We have or want a hard CI gate that fails PRs. The --format=github-actions output and the Nyholm Docker action make setup a few lines of YAML, which matters more than it sounds — cheap setup is what determines whether a quality gate survives its first quarter.
• We want machine-generated release-note input for changelogs.

Look elsewhere or skip when:

• The codebase is an application, not a library. A Laravel app's "public API" is HTTP routes, queues, and DB schema; this tool inspects PHP class signatures and will report almost nothing useful while adding a CI step.
• The team can't or won't maintain tags, or releases are continuous/trunk-based with no meaningful version boundary.
• We need behavioral contract testing (response shapes, serialization, events). Use consumer-driven contract tests or API snapshot tests instead — this tool will not catch a changed return value.
• Pre-1.0 packages where breakage is expected every minor. The gate will be noise, and a permanently red pipeline trains people to ignore failures.
• We need multi-language or OpenAPI/SDK-surface coverage. This is PHP/Composer-only.
• Risk tolerance: 603 stars and zero recorded dependents means the bus factor and ecosystem-validation story is thin. It is maintained and released, but it is a single-vendor tool (Roave) — worth a note in the risk register, and worth pinning the version rather than floating it.

Adoption caveat for a Laravel shop specifically: it slots in cleanly as a dev dependency alongside Pint/PHPStan/Pest in CI for packages we ship, but it should not be added to every repo by default. Blanket adoption is the failure mode: it produces a green check nobody reads in app repos and dilutes the signal where it actually matters.

How to Pitch It (Stakeholders)

To executives (one paragraph): We ship PHP packages that other teams and, in some cases, external developers build on. Right now nothing technically stops a release from silently breaking those consumers — we rely on a reviewer noticing a changed method signature. That failure mode is expensive and late: it surfaces as a support ticket or a blocked upgrade, not a build failure. roave/backward-compatibility-check is a free, MIT-licensed CLI that compares the current branch to the last release tag and fails CI if we've broken our public API. Setup is roughly ten lines of YAML. It converts a class of post-release incidents into a pre-merge build failure, and it auto-generates the "what changed" section of our release notes. It costs a few hours to pilot on one package, and if it's noisy we uninstall it.

To engineering (the honest version):

• Add roave/backward-compatibility-check as a dev dependency and one CI step, gated to published packages only. Use --format=github-actions so breaks annotate the PR diff instead of hiding in logs.
• Preconditions are real: full git history and tags in CI (fetch-depth: 0), SemVer x.y.z tags, and complete autoload coverage. Get those right first or the tool under-reports and we'll wrongly conclude it doesn't work.
• Coverage: added/removed/changed method signatures, visibility changes, added required parameters, enum case additions — i.e. the mechanical breakages that are easy to miss in review and tedious to check by hand.
• Not coverage: behavior, return-value semantics, database or config contract changes, anything outside reflected PHP symbols. It complements PHPStan and our test suite; it does not replace them.
• Use .roave-backward-compatibility-check.xml baselines sparingly. Every ignored regex should reference a ticket and an intended removal. An indefinitely growing baseline is a signal we've stopped honoring SemVer, not a signal the tool is bad.
• Pilot on the single highest-traffic package for one release cycle, measure how many real breaks it catches versus false positives, then decide on wider rollout.
• Known risk: single-vendor tool, modest community footprint (603 stars, no recorded dependents). Pin the version; if it's abandoned, the exit cost is one CI step and one dev dependency, so the downside is capped.