ADR-0004: Strict Semver with Automated BC Checks

Status

Accepted

Context

contentful-core.php is consumed by two public SDKs and their downstream framework integrations. Any unintentional public API break causes breakage for all consumers simultaneously. Manual backward-compatibility review is error-prone and doesn't scale.

The team's internal runbook defines the change-type / version-bump matrix:

• New feature (non-breaking) → minor bump
• Bug fix → patch bump
• Breaking change (including dropping a PHP version) → major bump

Decision

roave/backward-compatibility-check runs as a required CI job on every PR. It diffs the current branch against the prior git tag and reports any BC breaks. The job is configured with fetch-depth: 0 to ensure full git history is available.

Breaking changes are only allowed when accompanied by a deliberate major version bump documented in CHANGELOG.md.

Consequences

• Enables: Automated detection of BC breaks before merge; confidence for downstream SDK maintainers.
• Prevents: Silent API erosion. A refactor that changes a public method signature will fail CI unless intentionally versioned.
• Operational note: The BC checker can emit false positives on first-time setup or when comparing against a non-existent prior tag. The CI job uses || true to avoid hard-failing on these edge cases — this is intentional and should not be removed without updating the handling.
• Follow-up: The backwards-compatibility CI job was added as part of v3.1.3 improvements (2022-01-17 changelog).