migration-playbooklisted

# Migration Playbook A phased workflow for executing migrations safely. The core discipline: **inventory before strategy, safety net before execution, reviewable batches before merge.** Migrations fail not because the happy path is wrong, but because the affected surface was larger than expected, or the rollback story was never written. --- ## Phase 0: Inventory Enumerate every affected call site BEFORE changing a single line of production code. ```bash # Count and locate all usages of the thing being replaced grep -rn "oldImport\|OldAPI\|deprecated_fn" src/ --include="*.ts" | wc -l grep -rn "oldImport\|OldAPI\|deprecated_fn" src/ --include="*.ts" # For syntactic patterns, ast-grep gives structural matches ast-grep --pattern 'require("old-package")' --lang js # Categorize: how many usage *patterns* exist, not just raw sites? # e.g. "called with callback" vs "called with async/await" are two patterns ``` Read the official migration guide and CHANGELOG of the dependency **end-to-end** before writing code. Note every breaking change, removed API, and renamed option. Create a two-column table: old construct → new construct. Estimate blast radius: | Dimension | Low (<20 sites) | Medium (20-100) | High (>100) | | --------------- | --------------- | --------------- | ------------- | | Strategy | Big bang | Incremental | Codemod first | | Risk | Low | Medium | High | | Branch lifetime | Hours | Day