Deprecating and migrating: switching off an old system without leaving anyone behind

How to decide whether to keep or retire a system, and how to migrate users: code as a liability, deprecation with a deadline, gradual migration, removal only once usage is zero.

Methodologymetodologiamigrazionedeprecazioneingegneria del software19 November 2026 · 3 min read

Every line of code has a maintenance cost: it has to be read, updated, protected, tested. An old system that nobody loves but somebody still uses is a debt that keeps growing. Deprecating and migrating means deciding, with a method, when to retire something and how to move users elsewhere without surprises.

Code as a liability

The starting point is a change of perspective: code is not an asset to preserve, it is a liability to maintain. You keep it because it is needed, not because it was already written. The question is not "can we switch it off?" but "what does it cost to keep compared with what it gives?".

Deciding whether to retire

A few questions help.

  • Who still uses it, and how much? (With usage data, not impressions.)
  • Is there a replacement that really covers the use cases, or only the main ones?
  • What does it cost to keep (time, risk, rare skills)?
  • What happens to the remaining users, and on what terms can they be accompanied?

If the answer is "we don't know", the first job is to measure usage.

The deprecation process

1. Announce, with a date. Say what is being retired, why, what replaces it and by when. An announcement without a date produces no migrations.

2. Make migration possible. Provide the path: guide, tools, examples, support. If migrating is hard, users will not do it.

3. Flag usage. The old system warns whoever uses it (messages, headers, logs), so nobody is caught by surprise.

4. Migrate gradually. By groups, starting from the simplest or the most cooperative. The two systems run in parallel for as long as needed, and the results are compared.

5. Switch off when usage is zero (or when the residual usage has been decided to be acceptable). Not before. Switching off a system with active users is a service outage.

6. Remove. You delete the code, the configuration, the documentation and the data no longer needed (respecting retention obligations). The work is done when the code is gone, not when the notice has been sent.

Compatibility code

Code that keeps the old behaviour alive for old users has an end date: without one, it becomes permanent. It is marked with a comment saying who uses it and when it comes out.

Warning signs

  • A "deprecated" system with no switch-off date.
  • No measurement of real usage.
  • A replacement that does not cover all the use cases.
  • Switch-off with users still active.
  • Compatibility code with no expiry.
  • Two systems in parallel for years.

An example

An internal version-1 API is used by eleven services. Usage is measured: seven have already abandoned it, four have not. The switch-off is announced with a date, the migration guide is prepared and each of the four teams is followed up. A week before the date usage is zero: it is switched off, then the code is removed.

When to use it

When removing old systems, APIs or features; when migrating users from one implementation to another; when deciding whether to keep or retire existing code.

This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.

This article is an OIAR skill

What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.

deprecation-and-migrationA method for retiring a system and migrating its users: code as a liability, measuring usage, announcing with a date, migration path, warnings, gradual migration, switch-off at zero usage, complete removal. Use it when deciding whether to keep or retire code, APIs or features.