deprecation-and-migration

Deprecation and Migration

Overview

Remove and migrate safely. The goal of deprecation is to guide consumers away from old patterns without breaking them — giving adequate notice, providing a clear migration path, and removing dead code only after adoption is confirmed. Rushed deprecations break trust. Abandoned deprecations create maintenance debt.

When to Use

• Removing or changing a public API endpoint
• Renaming or restructuring modules or functions
• Migrating a database schema
• Upgrading a major dependency version
• Moving from one architectural pattern to another (monolith → microservices, REST → GraphQL)

The Deprecation Protocol

Stage 1: Plan (Before Writing Code)

BEFORE DEPRECATING, ANSWER:
1. Who uses this? (Use grep -rn via code_execution_tool to find all usages)
2. What is the migration path? (Don't deprecate without a replacement)
3. How long do consumers need? (Internal: 1-2 weeks. External: 1-6 months)
4. Can I migrate them automatically? (Script > docs > manual)
5. What breaks if I remove it today? (Test with code_execution_tool)

Stage 2: Communicate

For internal code:

// Mark with @deprecated JSDoc tag
/**
 * @deprecated Use `createTaskV2(input)` instead. Will be removed in v4.0.0.
 * Migration guide: see docs/migrations/task-api-v4.md
 */
export function createTask(title: string, priority: number): Task {
  console.warn('[DEPRECATED] createTask() is deprecated. Use createTaskV2() instead.');
  return createTaskV2({ title, priority: mapPriority(priority) });
}

For external APIs:

// HTTP Deprecation headers (RFC 8594)
app.post('/api/v1/tasks', (req, res) => {
  res.set('Deprecation', 'true');
  res.set('Sunset', 'Sat, 01 Jan 2026 00:00:00 GMT');
  res.set('Link', '</api/v2/tasks>; rel="successor-version"');

  // ... existing handler
});

Stage 3: Migrate

Prefer automated migration over documentation:

# Codemod for mechanical renames
npx jscodeshift -t ./codemods/rename-createTask.js src/

# Database migration (Prisma)
npx prisma migrate dev --name rename_priority_column

# Check remaining usages after migration
grep -rn "createTask(" src/ --include="*.ts" | grep -v "createTaskV2"