A widely-used internal library is being formally deprecated because a better-supported alternative has emerged. Walk through the deprecation lifecycle you'd run so that dozens of dependent teams migrate off it without a disruptive forced cutover.

## Why deprecation is the expensive part Deprecation is where a tech radar's governance work actually gets expensive, because moving a technology to Hold is a decision made in a meeting, while getting dozens of teams to actually stop depending on it is a multi-month execution problem with real engineering cost spread across other people's roadmaps. A lifecycle with distinct, well-defined phases exists specifically to make that execution problem tractable and to avoid the two bad outcomes: - a chaotic forced cutover that breaks production systems, or - an announcement that never actually gets enforced and the deprecated library quietly lives forever. ## The four phases 1. **Phase one, announce:** the decision — what's being deprecated, why (the replacement's specific advantages, or a genuine problem with the old library such as unpatched security debt or an unmaintained upstream), what the replacement is, and a target sunset date — gets published somewhere all dependent teams will actually see it, not buried in a wiki page nobody reads. Lead time here should scale with expected migration effort: a config-flag rename might reasonably get four weeks' notice, while a foundational library requiring API rewrites across fifty services might reasonably need six months to a year. Announcing too early, with no clear timeline, trains teams to ignore deprecation notices as noise; announcing with too little lead time turns migration into an emergency nobody had capacity to plan for. 2. **Phase two, deprecate-but-support:** the old library keeps working — critically, it keeps receiving security patches during this window, because forcing a security-vs-deadline trade-off onto every dependent team is exactly the kind of pressure that produces workarounds and shadow forks — while visibly signaling it's on its way out: a compiler or linter deprecation warning, a banner in generated documentation, a note in the library's own changelog. This is the phase where **dual-running** is expected and healthy; the point isn't instant cutover, it's making the coming change impossible to miss while giving teams a working system to migrate from at their own (bounded) pace. 3. **Phase three, migrate:** this is the phase most deprecation efforts under-invest in. A migration guide alone puts the entire burden on each of dozens of teams to independently figure out the mechanical transformation, which is both wasteful (the same problem gets solved fifty times) and slow. Where the change is mechanical enough, automated **codemods** (scripted refactoring tools) dramatically lower the real cost of migrating and should be treated as a first-class deliverable of the deprecation, not a nice-to-have. Equally important is visibility: someone should maintain a tracked, living list of remaining consumers — derived from actual usage telemetry or dependency-graph analysis, not self-reported status — so the organization can see migration progress as a number, not a vague sense that 'most people have probably moved.' 4. **Phase four, sunset:** only after the deadline passes and usage data shows the dependent count is genuinely near zero does active support stop (no further patches) and, eventually, does the library get physically removed or hard-blocked (e.g., pulled from the internal artifact repository, or a CI gate starts failing any build still referencing it). The critical discipline here is that the sunset date has to be real — if it's quietly extended for every team that didn't get around to migrating, the entire lifecycle loses credibility and every future deprecation gets ignored on the assumption the deadline is soft. The way to keep the date real without being reckless is a narrow, explicit exception process: a team with a genuine blocker (a vendor dependency that hasn't caught up, a system in a compliance freeze) gets a documented, time-bound extension with a named owner and a new date, not a silent, indefinite pass. ## Trade-offs - **A long, gentle lifecycle** costs calendar time and requires the organization to run two versions of the same capability in parallel for months, which has real maintenance cost. - **A short, aggressive lifecycle** reduces that dual-running cost but sharply increases the risk of breaking dependent teams who couldn't reprioritize in time, and tends to produce exactly the exception-request pileup that erodes deadline credibility. The right point on that spectrum scales with blast radius: a low-usage internal utility can sunset in weeks; a foundational library touching every service in the company needs a much longer runway and real migration tooling investment. ## Three ways it goes wrong **Failure modes in production:** - **An announcement with no funded migration effort behind it** — the most common. The deadline arrives, most teams haven't moved because nobody gave them time or tooling, and the org either breaks production or grants a blanket extension that becomes the new indefinite status quo. - **Deprecating without maintaining security patches during the support window** — a second. It forces teams into an unsafe choice. - **Having no usage telemetry** — a third. The team running the deprecation genuinely doesn't know who's still depending on it until the hard cutover breaks them. ## How this played out at internet scale A concrete instance: this is close to the shape of Python 2's end-of-life process — a long-announced sunset date (originally 2015, extended once to January 2020), years of dual-running support, extensive migration tooling (the 2to3 codemod and later compatibility shims like six), and, even after the formal EOL date passed, major distributions and package indexes maintained visible warnings for years afterward precisely because instant hard removal at internet scale would have broken far too much running software.