How to Announce a Breaking Change in English

Announcing a breaking change well is one of the clearest signals of a mature engineering team — it shows respect for the people depending on your API or library, even when the change itself is disruptive. A poorly written breaking-change announcement, missing a clear timeline or migration path, generates far more support tickets and frustration than the change itself usually warrants. This post covers the vocabulary and structure that make breaking-change communication clear, honest, and actionable for the people who have to respond to it.

Key Vocabulary

Breaking change — a modification to an API, library, or system that requires consumers to update their own code or configuration, or their existing integration will fail. “Renaming this field is a breaking change — anyone parsing the response by field name will need to update their code.”

Deprecation notice — an advance warning that a feature will be removed or changed in the future, giving consumers time to migrate before the breaking change actually takes effect. “We’re issuing a deprecation notice today for the v1 endpoint; it will remain functional for 90 days before removal.”

Migration guide — documentation that explains, step by step, how consumers should update their code to work with the new version after a breaking change. “The migration guide includes a code sample showing exactly how to update the authentication header format.”

Sunset date — the specific date on which a deprecated feature or version will stop working entirely. “The sunset date for the legacy webhook format is set for September 1st — after that, only the new payload structure will be delivered.”

Semantic versioning — a versioning convention where a major version increment specifically signals the presence of breaking changes, distinguishing them from backward-compatible minor or patch releases. “Following semantic versioning, this change ships as v3.0.0, not v2.5.0, because it’s not backward compatible.”

Backward compatibility — the property of a new version continuing to work correctly with code written against a previous version, without requiring changes. “We evaluated an approach that would preserve backward compatibility, but it would have meant maintaining two incompatible data formats indefinitely.”

Grace period — the window of time between announcing a breaking change and it actually taking effect, during which both old and new behavior are typically supported. “We’re offering a 60-day grace period where both the old and new response formats are available, controlled by a request header.”

Common Phrases

• “This is a breaking change and will require an update on your side — here’s exactly what to change.”
• “We’re giving a 90-day grace period before the old behavior is removed entirely.”
• “The migration guide walks through the three most common integration patterns we’ve seen.”
• “This change ships as a major version bump, per semantic versioning, precisely because it isn’t backward compatible.”
• “If you’re not able to migrate by the sunset date, please reach out — we can discuss an extension for confirmed edge cases.”
• “We know this is disruptive, and we’ve tried to make the migration path as short as possible.”

Example Sentences

Announcing the change to API consumers: “Starting with v3.0.0, the /orders endpoint will return total_amount as a string instead of a number, to avoid floating-point precision issues reported by several integrators. This is a breaking change. The previous behavior remains available at /v2/orders until the sunset date of October 15th, giving you a 60-day grace period to migrate. Full migration steps, including code samples in three languages, are in the linked guide.”

Responding to a consumer asking for more time: “Thanks for flagging your timeline constraints. We can extend your specific integration’s access to the legacy endpoint by an additional 30 days beyond the general sunset date, given the scope of the changes required on your end. Please let us know once your migration is complete so we can disable the extension.”

Explaining the rationale internally before the public announcement: “I’d like to propose we ship this as a major version with a 90-day grace period rather than a silent change, even though the fix is technically small. Several of our largest integrators parse this field by type, and a silent change would break their systems without warning, which is exactly the outcome a clear breaking-change announcement is meant to prevent.”

Professional Tips

• Always state explicitly that something is a breaking change — don’t bury this in neutral language like “we’ve updated the response format,” which can cause consumers to miss it entirely.
• Include a sunset date in every breaking-change announcement, not just a vague “in a future release” — a specific date lets consumers actually plan their migration.
• Provide a migration guide with real code samples alongside the announcement, not as a follow-up — teams are far more likely to act quickly when the path forward is immediately visible.
• Reference semantic versioning explicitly when applicable — it gives technical consumers a familiar, unambiguous signal about the scope of the change before they even read the details.

Practice Exercise

1. Write a three-sentence announcement of a breaking change to an authentication mechanism, including a sunset date and a link to a migration guide.
2. Draft a two-sentence response to a customer requesting a grace period extension, offering a reasonable compromise.
3. Explain, in two sentences, why a major version bump matters when announcing a breaking change to technical consumers.