Writing PR Descriptions for Breaking Changes

Option B follows the Conventional Commits breaking change convention and gives the caller the essential migration information in the title. The ! after feat signals a breaking change. The dash-separated migration hint ("callers must migrate to /api/v2/users") ensures the breaking nature is immediately clear even in notification emails and PR lists. Option A gives no signal of breaking change. Option C is unprofessional and vague. Option D uses "fix" (wrong type) and "deprecated" (not removed). A breaking change PR title should: signal the type (feat!/refactor!/fix!), name what changed, and ideally hint at the migration path.

Option B is correct. The opening paragraph of a breaking PR description must answer three questions immediately: (1) What breaks? — the specific API, behaviour, or contract that changes. (2) Who is affected? — which callers, consumers, or services. (3) When? — is this effective immediately, behind a feature flag, or scheduled for a deprecation period? Example: "This PR removes the GET /api/v1/users endpoint. Any service calling v1 will receive a 404 after this is merged. The v2 endpoint (/api/v2/users) has been live since 2024-Q3. Affected teams: Billing, Analytics." Lead with impact, not with implementation details.

Option B provides a complete migration guide in three sentences: (1) what was removed and from where, (2) what to use instead and why it's safe (values are identical), and (3) tooling to automate the migration. This is the gold standard for breaking change migration guidance. Every breaking PR should answer: what changed, what replaces it, and how to migrate (manually or with a script). Option A is vague and places the cognitive burden on the consumer without help. Option C is passive-aggressive. Option D outsources the information to another document — unhelpful in a PR review context. Make migration trivial for the consumer.

Option C is correct. A rollback plan in a breaking change PR must state: (1) whether rollback is possible, (2) how to do it (revert commit, toggle flag, etc.), and (3) any data or state implications of rolling back. Breaking changes often have asymmetric rollback risk — the new code deploys cleanly, but rolling back may require data migration. Documenting this upfront prevents panic during incidents. Example format: "Rollback: revert this commit and redeploy. Services that have already migrated to v2 will continue to work. No data migration required." Option A is uselessly brief. Option B may be true but gives no plan. Option D is unprofessional.

Option B — confirming that all consumers have been notified and have a migration plan — is the most critical gate before merging a breaking change. This prevents surprise production outages in dependent services. The checklist should include: "[ ] Affected teams notified (Slack #platform-consumers, email to billing-eng)", "[ ] Migration guide reviewed by at least one consumer team", "[ ] Deprecation period honoured (or waived by [stakeholder])". Option A (no warnings) is a general quality check, not specific to breaking changes. Option C (24 hours) is arbitrary. Option D (commit format) is good practice but not the most critical gate. Breaking changes require stakeholder alignment, not just code quality.