An internal platform must remove a capability that several teams depend on. How should the deprecation be run?

The principle

Treat internal consumers like external ones. They have the same migration costs and less patience, and a platform that breaks its users loses the voluntary adoption that makes it work.

The sequence

1. Know who depends on it, from telemetry rather than from a survey. "Which teams call this" must be answerable in minutes, and if it is not, that is the first thing to build.
2. Provide the replacement first, working and documented, before announcing the removal. A deprecation without a ready alternative is an instruction to build one yourself.
3. Provide migration tooling, not just documentation — a codemod, a compatibility shim, an automated conversion. The platform team migrating the consumers is frequently cheaper in total than every consumer team doing it themselves, and it is dramatically faster.
4. Announce with a real notice period, communicated in-band: warnings at the call site, in the CLI output, in the dashboard the developer uses — not an email, which reaches nobody who can act.
5. Track migration progress publicly, so the remaining consumers are visible and can be helped individually.
6. Brownouts before removal — brief scheduled unavailability — which makes the deadline real while it is still reversible.

What makes it fail

• No usage telemetry, so the consumer list is a guess and the removal breaks someone unknown.
• Announcement without a replacement, which is the most common form and the most damaging to trust.
• Email as the channel, since the original author has moved and the team alias is unmonitored.
• A deadline with no enforcement, which teaches everyone that deadlines are advisory and makes the next deprecation harder.
• Removing it during a peak or a freeze window, which converts a planned migration into an incident.

The trust dimension

A platform's ability to evolve depends on consumers believing that adopting it is safe. One badly-run deprecation makes teams reluctant to adopt the next capability, which is a cost paid on everything the platform ships afterwards.

That is why funding the migration is usually the right call: it costs the platform team a quarter and it preserves the property the platform depends on.