name: migrate-ops
description: "Framework and language migration patterns - version upgrades, breaking changes, dependency audit, safe rollback. Use for: migrate, migration, upgrade, version bump, breaking changes, deprecation, dependency audit, npm audit, pip-audit, codemod, jscodeshift, rector, rollback, semver, changelog, framework upgrade, language upgrade, React 19, Vue 3, Next.js App Router, Laravel 11, Angular, Python 3.12, Node 22, TypeScript 5, Go 1.22, Rust 2024, PHP 8.4."
license: MIT
allowed-tools: "Read Edit Write Bash Glob Grep Agent"
metadata:
author: claude-mods
related-skills: testing-ops, debug-ops, git-ops, refactor-ops
Migrate Operations
Comprehensive migration skill covering framework upgrades, language version bumps, dependency auditing, breaking change detection, codemods, and rollback strategies.
Migration Strategy Decision Tree
What kind of migration are you performing?
│
├─ Small library update (patch/minor version)
│ └─ In-place upgrade
│ Update dependency, run tests, deploy
│
├─ Major framework version (React 18→19, Vue 2→3, Laravel 10→11)
│ │
│ ├─ Codebase < 50k LOC, good test coverage (>70%)
│ │ └─ Big Bang Migration
│ │ Upgrade everything at once in a feature branch
│ │ Pros: clean cutover, no dual-version complexity
│ │ Cons: high risk, long branch life, merge conflicts
│ │
│ ├─ Codebase > 50k LOC, partial test coverage
│ │ └─ Incremental Migration
│ │ Upgrade module by module, use compatibility layers
│ │ Pros: lower risk per step, continuous delivery
│ │ Cons: dual-version code, longer total duration
│ │
│ ├─ Monolith → microservice or complete architecture shift
│ │ └─ Strangler Fig Pattern
│ │ Route new features to new system, migrate old features gradually
│ │ Pros: zero-downtime, reversible, production-validated
│ │ Cons: routing complexity, data sync challenges
│ │
│ └─ High-risk data pipeline or financial system
│ └─ Parallel Run
│ Run old and new systems simultaneously, compare outputs
│ Pros: highest confidence, catch subtle differences
│ Cons: double infrastructure cost, comparison logic
│
└─ Language version upgrade (Python 3.9→3.12, Node 18→22)
└─ In-place upgrade with CI matrix
Test against both old and new versions in CI
Drop old version support once all tests pass
Framework Upgrade Decision Tree
Which framework are you upgrading?
│
├─ React 18 → 19
│ ├─ Check: Remove forwardRef wrappers (ref is now a regular prop)
│ ├─ Check: Replace <Context.Provider> with <Context>
│ ├─ Check: Adopt useActionState / useFormStatus for forms
│ ├─ Check: Replace manual memoization if using React Compiler
│ ├─ Codemod: npx codemod@latest react/19/migration-recipe
│ └─ Load: ./references/framework-upgrades.md
│
├─ Next.js Pages Router → App Router
│ ├─ Check: Move pages/ to app/ with new file conventions
│ ├─ Check: Replace getServerSideProps/getStaticProps with async components
│ ├─ Check: Convert _app.tsx and _document.tsx to layout.tsx
│ ├─ Check: Update data fetching to use fetch() with caching options
│ ├─ Codemod: npx @next/codemod@latest
│ └─ Load: ./references/framework-upgrades.md
│
├─ Vue 2 → 3
│ ├─ Check: Replace Options API with Composition API (optional but recommended)
│ ├─ Check: Replace Vuex with Pinia
│ ├─ Check: Replace event bus with mitt or provide/inject
│ ├─ Check: Update v-model syntax (modelValue prop)
│ ├─ Tool: Migration build (@vue/compat) for incremental migration
│ └─ Load: ./references/framework-upgrades.md
│
├─ Laravel 10 → 11
│ ├─ Check: Adopt slim application skeleton
│ ├─ Check: Update config file structure (consolidated configs)
│ ├─ Check: Review per-second scheduling changes
│ ├─ Check: Update Dumpable trait usage
│ ├─ Tool: laravel shift (automated upgrade service)
│ └─ Load: ./references/framework-upgrades.md
│
├─ Angular (any major version)
│ ├─ Check: Run ng update for guided migration
│ ├─ Check: Review Angular Update Guide (update.angular.io)
│ ├─ Tool: ng update @angular/core @angular/cli
│ └─ Load: ./references/framework-upgrades.md
│
└─ Django (any major version)
├─ Check: Run python -Wd manage.py test for deprecation warnings
├─ Check: Review Django release notes for removals
├─ Tool: django-upgrade (automatic fixer)
└─ Load: ./references/framework-upgrades.md
Dependency Audit Workflow
Ecosystem?
│
├─ JavaScript / Node.js
│ ├─ npm audit / npm audit fix
│ ├─ npx audit-ci --moderate (CI integration)
│ └─ Socket.dev for supply chain analysis
│
├─ Python
│ ├─ pip-audit
│ ├─ safety check
│ └─ pip-audit --fix (auto-update vulnerable packages)
│
├─ Rust
│ ├─ cargo audit
│ └─ cargo deny check advisories
│
├─ Go
│ ├─ govulncheck ./...
│ └─ go list -m -u all (list available updates)
│
├─ PHP
│ ├─ composer audit
│ └─ composer outdated --direct
│
└─ Multi-ecosystem
└─ Trivy, Snyk, or Dependabot across all
Pre-Migration Checklist
[ ] Test coverage measured and documented (target: >70% for critical paths)
[ ] CI pipeline green on current version
[ ] All dependencies up to date (or pinned with rationale)
[ ] Database backup taken (if applicable)
[ ] Git state clean — migration branch created from latest main
[ ] Rollback plan documented and tested
[ ] Breaking change list reviewed from upstream changelog
[ ] Team notified of migration window
[ ] Feature flags in place for gradual rollout (if applicable)
[ ] Monitoring and alerting configured for regression detection
[ ] Performance baseline captured (response times, memory, CPU)
[ ] Lock file committed (package-lock.json, yarn.lock, Cargo.lock, etc.)
Breaking Change Detection Patterns
How do you detect breaking changes?
│
├─ Semver Analysis
│ ├─ Major version bump → breaking changes guaranteed
│ ├─ Check CHANGELOG.md or BREAKING_CHANGES.md in repo
│ └─ npm: npx npm-check-updates --target major
│
├─ Changelog Parsing
│ ├─ Search for: "BREAKING", "removed", "deprecated", "renamed"
│ ├─ GitHub: compare releases page between versions
│ └─ Read migration guide if one exists
│
├─ Compiler / Runtime Warnings
│ ├─ Enable all deprecation warnings before upgrading
│ ├─ Python: python -Wd (turn deprecation warnings to errors)
│ ├─ Node: node --throw-deprecation
│ └─ TypeScript: strict mode catches type-level breaks
│
├─ Codemods (automated detection + fix)
│ ├─ jscodeshift — JavaScript/TypeScript AST transforms
│ ├─ ast-grep — language-agnostic structural search/replace
│ ├─ rector — PHP automated refactoring
│ ├─ gofmt / gofumpt — Go formatting changes
│ └─ 2to3 — Python 2 to 3 (legacy)
│
└─ Type Checking
├─ TypeScript: tsc --noEmit catches API shape changes
├─ Python: mypy / pyright after upgrade
└─ Go: go vet ./... after upgrade
Codemod Quick Reference
| Ecosystem |
Tool |
Command |
Use Case |
| JS/TS |
jscodeshift |
npx jscodeshift -t transform.ts src/ |
Custom AST transforms |
| JS/TS |
ast-grep |
sg --pattern 'old($$$)' --rewrite 'new($$$)' |
Structural find/replace |
| React |
react-codemod |
npx codemod@latest react/19/migration-recipe |
React version upgrades |
| Next.js |
next-codemod |
npx @next/codemod@latest |
Next.js version upgrades |
| Vue |
vue-codemod |
npx @vue/codemod src/ |
Vue 2 to 3 transforms |
| PHP |
Rector |
vendor/bin/rector process src |
PHP version + framework upgrades |
| Python |
pyupgrade |
pyupgrade --py312-plus *.py |
Python version syntax upgrades |
| Python |
django-upgrade |
django-upgrade --target-version 5.0 *.py |
Django version upgrades |
| Go |
gofmt |
gofmt -w . |
Go formatting updates |
| Go |
gofix |
go fix ./... |
Go API changes |
| Rust |
cargo fix |
cargo fix --edition |
Rust edition migration |
| Multi |
ast-grep |
sg scan --rule rules.yml |
Any language with custom rules |
Rollback Strategy Decision Tree
Migration failed or caused issues — how to roll back?
│
├─ Code-only change, no data migration
│ ├─ Small number of commits
│ │ └─ Git Revert
│ │ git revert --no-commit HEAD~N..HEAD && git commit
│ │ Pros: clean history, safe for shared branches
│ │ Cons: merge conflicts if code has diverged
│ │
│ └─ Entire feature branch
│ └─ Revert merge commit
│ git revert -m 1 <merge-commit-sha>
│
├─ Feature flag controlled
│ └─ Toggle flag off
│ Instant rollback, no deployment needed
│ Keep old code path until new path is proven
│
├─ Database schema changed
│ ├─ Reversible migration exists
│ │ └─ Run down migration
│ │ rails db:rollback / php artisan migrate:rollback / alembic downgrade
│ │
│ └─ Irreversible migration (dropped column, changed type)
│ └─ Restore from backup + replay write-ahead log
│ This is why you take backups BEFORE migration
│
└─ Infrastructure / deployment
├─ Blue-Green deployment
│ └─ Switch traffic back to blue (old) environment
│
├─ Canary deployment
│ └─ Route 100% traffic back to stable version
│
└─ Container orchestration (K8s)
└─ kubectl rollout undo deployment/app
Common Gotchas
| Gotcha |
Why It Happens |
Prevention |
| Upgrading multiple major versions at once |
Each major version may have sequential breaking changes that compound |
Upgrade one major version at a time, verify, then proceed |
| Lock file not committed before migration |
Cannot reproduce pre-migration dependency state |
Always commit lock files; take a snapshot branch before starting |
| Running codemods without committing first |
Cannot diff what the codemod changed vs your manual changes |
Commit clean state, run codemod, commit codemod changes separately |
| Ignoring deprecation warnings in current version |
Deprecated APIs are removed in next major version |
Fix all deprecation warnings BEFORE upgrading |
| Testing only happy paths after migration |
Edge cases and error paths are most likely to break |
Run full test suite plus manual exploratory testing |
| Not checking transitive dependencies |
A direct dep upgrade may pull in incompatible transitive deps |
Use npm ls, pip show, cargo tree to inspect dependency tree |
| Assuming codemods catch everything |
Codemods handle common patterns, not all patterns |
Review codemod output manually; check for skipped files |
| Skipping the migration guide |
Framework authors document known pitfalls and workarounds |
Read the official migration guide end-to-end before starting |
| Migrating in a long-lived branch |
Main branch diverges, causing painful merge conflicts |
Use feature flags for incremental migration on main |
| Not updating CI to test both versions |
CI passes on old version but new version has failures |
Add matrix testing for both versions during transition |
| Database migration without backup |
Irreversible schema changes with no recovery path |
Always backup before migration; test rollback procedure |
| Forgetting to update Docker/CI base images |
Code upgraded but runtime is still old version |
Update Dockerfile FROM, CI config, and deployment manifests |
Reference Files
| File |
Contents |
Lines |
references/framework-upgrades.md |
React 18→19, Next.js Pages→App Router, Vue 2→3, Laravel 10→11, Angular, Django upgrade paths |
~700 |
references/language-upgrades.md |
Python 3.9→3.13, Node 18→22, TypeScript 4→5, Go 1.20→1.23, Rust 2021→2024, PHP 8.1→8.4 |
~600 |
references/dependency-management.md |
Audit tools, update strategies, lock files, monorepo deps, supply chain security |
~550 |
See Also
| Skill |
When to Combine |
testing-ops |
Ensuring test coverage before migration, writing regression tests after |
debug-ops |
Diagnosing failures introduced by migration, bisecting breaking commits |
git-ops |
Branch strategy for migration, git bisect to find breaking change |
refactor-ops |
Code transformations that often accompany version upgrades |
ci-cd-ops |
Updating CI pipelines to test against new versions, matrix builds |
container-orchestration |
Updating base images, Dockerfile changes for new runtime versions |
security-ops |
Vulnerability remediation that triggers dependency upgrades |
