Part 4 · 1 chapters · ~8 min

Deprecations People Actually Finish

Announcements with dates and migration paths, Deprecation and Sunset headers, per-consumer usage tracking, direct outreach, brownouts, 410 Gone, internal deprecations with lint rules and import bans, and deleting the code at the end.

5

Dates, signals, brownouts, deletion

code
HTTP/1.1 200 OK
Deprecation: @1767225600                 # RFC 9745: deprecated since this Unix time
Sunset: Thu, 01 Apr 2027 00:00:00 GMT    # RFC 8594: will stop working
Link: <https://docs.acme.dev/migrate/v2-transfers>; rel="deprecation"

-- per-consumer usage to drive outreach
SELECT api_key_owner, count(*) FROM api_requests
WHERE route = 'POST /v1/transfers' AND ts > now() - interval '7 days'
GROUP BY 1 ORDER BY 2 DESC LIMIT 20;

Internal deprecations use the same steps with tooling: a lint rule that warns on new imports of the old library, then errors on new code, an allow-list of existing users that only shrinks, and a burndown (previous part).

A DEPRECATION THAT FINISHES
announce, measure, help, enforce, remove
announcedate, reason, migrationpath
swipe the figure sideways, or tap expand for full screen
1/5
announce
A deprecation notice says what is going, why, the replacement, the migration guide and the sunset date. Without a date it is a suggestion.
a date, a path, a reasonno date = no deprecation