deprecation-and-migration

Deprecation and Migration - Guide to Code Deprecation and System Migration

Skill Overview

Deprecation and Migration is an engineering practice guide focused on safely removing legacy code and migrating systems. It helps teams decide when to deprecate, how to migrate, how to validate the process, and how to prevent technical debt from accumulating.

Applicable Scenarios

1. Replacing Legacy Systems, APIs, or Libraries

When an existing implementation poses security risks, has excessive maintenance costs, or a new system is ready, this skill provides complete deprecation processes and migration strategies, including gradual migration approaches such as the Strangler pattern and Adapter pattern.

2. Cleaning Up Unmaintained Zombie Code

Identify and handle code that “nobody maintains but everyone uses,” including modules that have not been updated for a long time but still have active consumers, dependencies with security vulnerabilities, and systems with outdated documentation.

3. Database Schema Migration

For high-risk data-layer migrations, use the Expand/Contract pattern to ensure that every step can be deployed and rolled back independently, avoiding missing fields or query failures during release windows.

Core Features

1. Deprecation Decision Framework

Evaluate whether a system should be deprecated through five key questions: Does it still provide unique value? How many dependent users are there? Is there an alternative? What is the migration cost? What would the maintenance cost be if it is not deprecated? Distinguish between mandatory and advisory deprecation to avoid forcing users to migrate unnecessarily.

2. Progressive Migration Pattern Library

Provides several proven migration patterns:

Strangler Pattern: Run the new and old systems in parallel, gradually shifting traffic from the old system to the new one

Adapter Pattern: Preserve the old interface while switching the underlying implementation to the new one

Feature-Flag Migration: Switch users or services over individually to reduce risk

Expand/Contract Pattern: A safe approach to database migration: add first, then remove, avoiding in-place modifications

3. Migration Validation Checklist

A post-deprecation validation checklist, including: the replacement has been validated in production, migration documentation is complete, all active consumers have migrated (verified through metrics/logs), legacy code/tests/documentation/configuration have been completely removed, and deprecation announcements have been taken down. For database migrations, additionally verify that each phase can be rolled back independently, backfill scripts are executed in batches, and destructive changes are deployed separately.

Frequently Asked Questions

When should code be deprecated instead of continuing to maintain it?

Code should be deprecated when the system no longer provides unique value, an active alternative exists, and the maintenance costs—such as security risks, engineering time, and opportunity costs—exceed the migration costs. If migration costs are too high, begin with advisory deprecation, such as warnings, documentation, and prompts, to allow users to migrate on their own. Switch to mandatory deprecation only when maintenance costs become unsustainable.

Why use the Expand/Contract pattern for database migrations instead of modifying the schema directly?

Because old and new code run simultaneously during the release window. If a field is renamed or deleted directly, half of the code may query a nonexistent field and fail. The Expand/Contract pattern ensures that both old and new code remain valid at every stage: first add the new field as nullable, then write to both fields, backfill the data, switch reads to the new field, and finally delete the old field. Each step can be deployed and rolled back independently.

How should zombie code that nobody maintains but everyone uses be handled?

Zombie code cannot remain unattended indefinitely. Either allocate resources to maintain it properly or create a specific deprecation and migration plan. Signs of zombie code include: no commits for more than six months despite active consumers, no assigned maintainer, failing tests that nobody fixes, dependencies with known vulnerabilities that nobody updates, and documentation that references nonexistent systems.