deprecation-and-migration

Name: deprecation-and-migration
Author: addyosmani

byaddyosmani· 31 skills

Installs

14k

Stars

80k

Forks

8.7k

How to install deprecation-and-migration?

addyosmani/agent-skills/deprecation-and-migration

$npx -y skills add addyosmani/agent-skills --skill deprecation-and-migration

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/addyosmani/agent-skills" --skill "addyosmani/agent-skills/deprecation-and-migration"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/addyosmani/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/addyosmani/agent-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Deprecation and Migration
2
3	## Overview
4
5	Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.
6
7	Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.
8
9	## When to Use
10
11	- Replacing an old system, API, or library with a new one
12	- Sunsetting a feature that's no longer needed
13	- Consolidating duplicate implementations
14	- Removing dead code that nobody owns but everybody depends on
15	- Planning the lifecycle of a new system (deprecation planning starts at design time)
16	- Deciding whether to maintain a legacy system or invest in migration
17
18	## Core Principles
19
20	### Code Is a Liability
21
22	Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
23
24	### Hyrum's Law Makes Removal Hard
25
26	With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.
27
28	### Deprecation Planning Starts at Design Time
29
30	When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.
31
32	## The Deprecation Decision
33
34	Before deprecating anything, answer these questions:
35
36	```
37	1. Does this system still provide unique value?
38	→ If yes, maintain it. If no, proceed.
39
40	2. How many users/consumers depend on it?
41	→ Quantify the migration scope.
42
43	3. Does a replacement exist?
44	→ If no, build the replacement first. Don't deprecate without an alternative.
45
46	4. What's the migration cost for each consumer?
47	→ If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
48
49	5. What's the ongoing maintenance cost of NOT deprecating?
50	→ Security risk, engineer time, opportunity cost of complexity.
51	```
52
53	## Compulsory vs Advisory Deprecation
54
55	\| Type \| When to Use \| Mechanism \|
56	\|------\|-------------\|-----------\|
57	\| Advisory \| Migration is optional, old system is stable \| Warnings, documentation, nudges. Users migrate on their own timeline. \|
58	\| Compulsory \| Old system has security issues, blocks progress, or maintenance cost is unsustainable \| Hard deadline. Old system will be removed by date X. Provide migration tooling. \|
59
60	Default to advisory. Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.
61
62	## The Migration Process
63
64	### Step 1: Build the Replacement
65
66	Don't deprecate without a working alternative. The replacement must:
67
68	- Cover all critical use cases of the old system
69	- Have documentation and migration guides
70	- Be proven in production (not just "theoretically better")
71
72	### Step 2: Announce and Document
73
74	```markdown
75	## Deprecation Notice: OldService
76
77	Status: Deprecated as of 2025-03-01
78	Replacement: NewService (see migration guide below)
79	Removal date: Advisory — no hard deadline yet
80	Reason: OldService requires manual scaling and lacks observability.
81	NewService handles both automatically.
82
83	### Migration Guide
84	1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
85	2. Update configuration (see examples below)
86	3. Run the migration verification script: `npx migrate-check`
87	```
88
89	### Step 3: Migrate Incrementally
90
91	Migrate consumers one at a time, not all at once. For each consumer:
92
93	```
94	1. Identify all touchpoints with the deprecated system
95	2. Update to use the replacement
96	3. Verify behavior matches (tests, integration checks)
97	4. Remove references to the old system
98	5. Confirm no regressions
99	```
100
101	The Churn Rule: If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.
102
103	### Step 4: Remove the Old System
104
105	Only after all consumers have migrated:
106
107	```
108	1. Verify zero active usage (metrics, logs, dependency analysis)
109	2. Remove the code
110	3. Remove associated tests, documentation, and configuration
111	4. Remove the deprecation notices
112	5. Celebrate — removing code is an achievement
113	```
114
115	## Migration Patterns
116
117	### Strangler Pattern
118
119	Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.
120
121	```
122	Phase 1: New system handles 0%, old handles 100%
123	Phase 2: New system handles 10% (canary)
124	Phase 3: New system handles 50%
125	Phase 4: New system handles 100%, old system idle
126	Phase 5: Remove old system
127	```
128
129	### Adapter Pattern
130
131	Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.
132
133	```typescript
134	// Adapter: old interface, new implementation
135	class LegacyTaskService implements OldTaskAPI {
136	constructor(private newService: NewTaskService) {}
137
138	// Old method signature, delegates to new implementation
139	getTask(id: number): OldTask {
140	const task = this.newService.findById(String(id));
141	return this.toOldFormat(task);
142	}
143	}
144	```
145
146	### Feature Flag Migration
147
148	Use feature flags to switch consumers from old to new system one at a time:
149
150	```typescript
151	function getTaskService(userId: string): TaskService {
152	if (featureFlags.isEnabled('new-task-service', { userId })) {
153	return new NewTaskService();
154	}
155	return new LegacyTaskService();
156	}
157	```
158
159	### Database Schema Migrations (Expand/Contract)
160
161	A schema change is the riskiest migration because the data is the one thing you cannot roll back by reverting a deploy. The failure mode is coupling the schema change to the code change: rename a column in the same release that starts using the new name, and during the rollout window — when old and new code run at once — one of them is querying a column that doesn't exist. The fix is to never change a column in place. Migrate in additive phases so old and new code are both valid at every step.
162
163	```
164	EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
165	add the new column, backfill existing rows, once no code reads the
166	nullable, alongside dual-write old+new from old column, drop it in
167	the old one the app a later, separate deploy
168	```
169
170	Worked example — renaming `name` to `full_name`:
171
172	1. Expand. Add `full_name` as nullable. Deploy. (Old code ignores it; nothing breaks.)
173	2. Dual-write. App writes both `name` and `full_name` on every insert/update. Deploy.
174	3. Backfill. Copy `name → full_name` for existing rows, in batches, so you don't lock the table.
175	4. Switch reads. Point the app at `full_name`, keep writing both. Deploy and bake.
176	5. Contract. Stop writing `name`, then — in a separate, later deploy — drop the column.
177
178	Each step is independently deployable and reversible: if step 4 misbehaves, roll the code back and `full_name` is still being populated. Treat each phase as a thin vertical slice — see the `incremental-implementation` skill.
179
180	Rules:
181	- Additive first, destructive last and alone. Adds (new nullable column, new table, new index) are safe in any deploy; drops and renames get their own deploy after no code references the old shape.
182	- Every migration has a tested down path. A migration you can't reverse is a deploy you can't roll back. Write and run the `down` before merging.
183	- Backfill in batches, off the hot path. A single `UPDATE` over millions of rows locks the table; chunk it and throttle.
184	- Build large indexes without blocking writes (e.g. Postgres `CREATE INDEX CONCURRENTLY`).
185	- Decouple from code by feature flag when the cutover is risky, exactly as in the Feature Flag Migration pattern above.
186
187	## Zombie Code
188
189	Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:
190
191	- No commits in 6+ months but active consumers exist
192	- No assigned maintainer or team
193	- Failing tests that nobody fixes
194	- Dependencies with known vulnerabilities that nobody updates
195	- Documentation that references systems that no longer exist
196
197	Response: Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.
198
199	## Common Rationalizations
200
201	\| Rationalization \| Reality \|
202	\|---\|---\|
203	\| "It still works, why remove it?" \| Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently. \|
204	\| "Someone might need it later" \| If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding. \|
205	\| "The migration is too expensive" \| Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term. \|
206	\| "We'll deprecate it after we finish the new system" \| Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now. \|
207	\| "Users will migrate on their own" \| They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule). \|
208	\| "We can maintain both systems indefinitely" \| Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost. \|
209	\| "Just rename the column, it's one line" \| During the rollout, old and new code run together — one will query a column that no longer exists. Expand/contract, never rename in place. \|
210	\| "I'll add the column and drop the old one in the same migration" \| That couples a safe add to a destructive drop. Drops get their own deploy, after no code references the old shape. \|
211	\| "We'll write the rollback if we need it" \| A migration with no down path is a deploy you can't reverse. Write and run the `down` before merging. \|
212
213	## Red Flags
214
215	- Deprecated systems with no replacement available
216	- Deprecation announcements with no migration tooling or documentation
217	- "Soft" deprecation that's been advisory for years with no progress
218	- Zombie code with no owner and active consumers
219	- New features added to a deprecated system (invest in the replacement instead)
220	- Deprecation without measuring current usage
221	- Removing code without verifying zero active consumers
222	- A schema change and the code that depends on it shipped in the same deploy
223	- A column renamed or dropped in place rather than via expand/contract
224	- A migration merged with no tested down path, or a backfill that locks the table
225
226	## Verification
227
228	After completing a deprecation:
229
230	- [ ] Replacement is production-proven and covers all critical use cases
231	- [ ] Migration guide exists with concrete steps and examples
232	- [ ] All active consumers have been migrated (verified by metrics/logs)
233	- [ ] Old code, tests, documentation, and configuration are fully removed
234	- [ ] No references to the deprecated system remain in the codebase
235	- [ ] Deprecation notices are removed (they served their purpose)
236
237	After a database schema migration:
238
239	- [ ] The change ships in additive phases (expand → backfill → contract), not a single in-place edit
240	- [ ] Old and new code are both valid against the schema at every deploy step
241	- [ ] Each migration has a tested down path; backfills run in throttled batches
242	- [ ] Destructive steps (drop/rename) ship in their own deploy after no code references the old shape

6 picks

Type

Run `npx skills use "https://github.com/addyosmani/agent-skills" --skill "addyosmani/agent-skills/deprecation-and-migration"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/addyosmani/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/addyosmani/agent-skills"` and select the relevant skills, then follow their instructions.

deprecation-and-migration

How to install deprecation-and-migration?

Related

deprecation-and-migration

How to install deprecation-and-migration?

Related