A platform must deprecate an API or capability that many teams depend on. How is this done without destroying trust or stalling indefinitely?

Why this is the hardest thing a platform team does

Every deprecation is the platform imposing work on its users for the platform's benefit. That framing is accurate and it is how teams experience it, so the process must be unusually careful — a platform that deprecates carelessly loses voluntary adoption, and voluntary adoption is the only honest signal it has.

The sequence

1. Know who is using it. Instrument usage before announcing anything. The list is always different from expectations, and announcing a deprecation and then discovering an unknown critical consumer is the worst possible start.

2. Build and prove the replacement first. Announcing a deprecation before the alternative exists and works is how a deprecation runs for three years. The replacement must be genuinely better for the user, not merely better for the platform.

3. Make migration cheap. Automated tooling, a codemod, a compatibility shim, or the platform team doing the work. The migration effort per team is the single variable that determines whether this completes, and it is the one the platform team can most directly control.

4. Announce with a date and a reason, personally to the heaviest users. A broadcast announcement reaches nobody who matters.

5. Make the old path visibly deprecated — warnings in logs, in the CLI, in the dashboard — so the signal reaches the person doing the work rather than the mailing-list subscriber.

6. Track migration progress publicly, per team. Visibility does most of the work.

7. Help the stragglers directly. The last 10% are unowned services, teams in crisis, or systems whose owner has left. They will not migrate on their own and no amount of communication changes that — someone has to do it for them, and budgeting for that is what distinguishes a completed deprecation from a permanent one.

8. Remove it, on the date. If the date slips repeatedly, every future deadline is treated as fictional, and the platform loses the ability to deprecate anything.

What preserves trust

• A long enough window — measured in quarters for a significant capability.
• A stated support policy so deprecation timelines are predictable rather than a surprise each time.
• Never breaking without a replacement, and never deprecating for aesthetic reasons.
• Absorbing the cost where the platform benefits most, which is honest and is what earns the next deprecation.
• Grandfathering genuinely hard cases rather than forcing an unreasonable migration, which costs the platform a little and preserves the relationship.

What destroys it

• Deprecating something with no replacement.
• Short notice, or a date that moves.
• Deprecating for the platform team's convenience with no user benefit — teams can tell, and they remember.
• Leaving teams to discover it from a changelog.
• Repeated deprecations in the same area, which teaches teams that adopting anything new is a liability — the most damaging outcome, because it suppresses adoption of everything the platform ships afterwards.