Design Deprecation Notices That Give People Time

Systems & Architecture · apis, developer, trust

Updated 2026-08-04

Announce a removal where the thing is used, not only where announcements live. A banner on the dashboard reaches people who will never read a changelog.
Give the notice the four facts it needs to be actionable:

Use semantic versioning as a promise rather than a label. A major version signals that existing usage will break, a minor one adds capability, and a patch fixes behavior, so a breaking change hidden in a patch destroys the only signal you had.
Keep the old path working alongside the new one for a stated window. Removal and replacement on the same day is not a migration, it is an outage with documentation.
Escalate on a schedule instead of shouting once. A quiet note months out, a clear warning weeks out, and a prominent one in the final days respects both the calendar and the reader.
Show whether this particular account is affected. A generic warning shown to everyone is ignored by everyone, and You are still calling this on 3 integrations is not.
Never remove something silently because usage looks low. Low usage often means a handful of accounts depend on it completely.
Log the last time each deprecated path was used, and surface it. That number is what lets you decide the removal date honestly rather than optimistically.

A deprecation is a promise about the future, and the interface is where you either keep it or quietly break it.