migrate-ops

What this skill does

# 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 d