practice

Deprecation Window

The stated period between announcing that an internal interface will be removed and removing it, with the removal actually happening at the end.

Removing something dozens of internal teams depend on has one hard part, and it is not technical. It is that consuming teams have their own priorities, and migrating off a working interface will lose to almost everything else on their backlog unless the deadline is credible.

Credibility is built by the first removal that actually happens. Until then, announced dates are treated as advisory, and they are usually right to be — most organisations extend the first few deadlines, which teaches everyone that deadlines extend.

The mechanics that make a window workable: measure who is still using it, by identity, and tell them individually rather than announcing broadly; provide the migration path and, where possible, do the migration for the largest consumers; publish a burndown of remaining callers so progress is visible; and introduce brownouts — short deliberate outages of the deprecated interface before removal — which surface consumers that instrumentation missed and convert an abstract deadline into a felt one.