deprecation-and-migration

Name: deprecation-and-migration
Author: addyosmani

13kinstalls8.6kforks

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.

Summary

Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.

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

People who liked this also viewed

6 picks

Type

deprecation-and-migration

13kinstalls8.6kforks

View on GitHub

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.

Summary

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

People who liked this also viewed

6 picks

Type