`, `<meta>` in components | Use built-in metadata support | | Asset references | New asset handling | Update import patterns for assets | | `useFormStatus` | New hook for forms | Replace manual form state | | `useOptimistic` | New hook | Replace manual optimistic updates | | `useActionState` | New hook | Replace reducer patterns for form actions | | Removed: `propTypes` warnings | Cleanup | Remove PropTypes if unused | | Context as provider | `<Context>` as provider | Replace `<Context.Provider>` with `<Context>` | **Migration Steps:** ```jsx // BEFORE (React 18) const ThemeContext = createContext('light'); <ThemeContext.Provider value="dark"><App /></ThemeContext.Provider> // AFTER (React 19) const ThemeContext = createContext('light'); <ThemeContext value="dark"><App /></ThemeContext> ``` ```jsx // BEFORE: ref callback <input ref={(node) => { node.focus(); }} /> // AFTER: ref callback with cleanup <input ref={(node) => { node.focus(); return () => { /* cleanup */ }; }} /> ``` **New Hooks (React 19):** ```jsx import { useActionState, useOptimistic, useFormStatus } from 'react'; // useFormStatus — must be in a child component function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>{pending ? 'Submitting...' : 'Submit'}</button>; } // useOptimistic function LikeButton({ postId, likes }) { const [optimisticLikes, addOptimisticLike] = useOptimistic( likes, (state, newLike) => state + 1 ); // ... } ``` **Breaking Change Detection Patterns (React):** ``` # Search for removed patterns grep -rn "ReactDOM.render" src/ grep -rn "unmountComponentAtNode" src/ grep -rn "renderToNodeStream" src/ grep -rn "Context\.Provider" src/ grep -rn "propTypes" src/ grep -rn "defaultProps.*function" src/ # defaultProps on function components removed in 18.3+ # Search for potential batching issues grep -rn "setTimeout\|requestAnimationFrame" src/ # May need flushSync grep -rn "flushSync" src/ # Verify still needed after migration ``` --- ### 2. Node.js 16 → 18 → 20 #### 16 → 18 | Change | Impact | Action | |--------|--------|--------| | V8 engine upgrade (10.1 → 10.2) | Performance | Benchmark critical paths | | `fetch` global available | New API | Can remove node-fetch dependency | | `Web Streams` API stable | New API | Consider for stream processing | | `test` runner (stable) | New tool | Consider replacing Jest/Mocha for unit tests | | `.env` file support via `--env-file` | New feature | Can remove dotenv dependency | | `fs.glob` | New API | Use for file globbing | | Permission model (experimental) | Security | Evaluate for production | | `vm.compileFunction` cache | Performance | Update if using vm module | **ESM Migration (Critical for Node 16→18):** ```json // package.json — set type to ESM { "type": "module" } ``` ```js // BEFORE (CJS) const express = require('express'); const path = require('path'); module.exports = { handler }; // AFTER (ESM) import express from 'express'; import path from 'path'; import { fileURLToPath } from 'url'; export { handler }; // Common ESM gotchas: // __dirname → import.meta.dirname (Node 20+) or: const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // require() → dynamic import() // BEFORE: const foo = require('./foo'); // AFTER: const foo = await import('./foo'); ``` **Conditional Exports in package.json:** ```json { "exports": { ".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs", "default": "./dist/index.mjs" } } } ``` #### 18 → 20 | Change | Impact | Action | |--------|--------|--------| | Stable `test` runner | Production ready | Migrate from Jest/Vitest if desired | | `import.meta.dirname` / `.filename` | ESM convenience | Remove fileURLToPath workarounds | | `fs.glob` stable | File operations | Simplify glob operations | | Permission model (stable) | Security | Evaluate | | Single executable apps | Distribution | Consider for CLI tools | | `readableStream.from`, `Readable.fromWeb` | Streams | Modernize stream usage | | `WebSocket` global | New API | Can remove ws dependency | | Performance improvements | ~10-15% faster | Benchmark | **Breaking Change Detection Patterns (Node.js):** ```bash # Check for CJS patterns that need ESM migration grep -rn "require(" src/ --include="*.js" grep -rn "module\.exports" src/ --include="*.js" # Check for __dirname/__filename (ESM incompatible) grep -rn "__dirname\|__filename" src/ # Check for JSON imports (need assert type) grep -rn 'import.*\.json' src/ # Check for native module dependencies (may need rebuild) grep -rn "node-gyp\|prebuild\|napi\|node-addon-api" package.json cat package.json | grep -E "bcrypt|canvas|sharp|sqlite3|node-sass|fsevents|better-sqlite3|cpu-features|esbuild|" # Check Node version in CI/CD grep -rn "node.*16\|node.*18" .github/workflows/ .gitlab-ci.yml Dockerfile docker-compose.yml ``` --- ### 3. Python 3.9 → 3.10 → 3.11 → 3.12 #### 3.9 → 3.10 | Change | Impact | Action | |--------|--------|--------| | Structural Pattern Matching (`match/case`) | New feature | Refactor complex if/elif chains | | `ParamSpec` and `Concatenate` | Type hints | Enhanced generic typing | | `int.bit_count()` | Performance | Replace bin(x).count('1') | | `zip(strict=True)` | Debugging | Use for catching length mismatches | | Error messages improved | DX | Update expected error patterns | | `bisect` now key functions | Performance | Simplify sorted lookups | | `|` for union types | Type hints | Replace `Union[X, Y]` with `X \| Y` | ```python # BEFORE: Union types from typing import Union, Optional def process(data: Union[str, int, None]) -> Optional[dict]: ... # AFTER: Python 3.10+ def process(data: str | int | None) -> dict | None: ... # Structural Pattern Matching def handle_command(cmd: str) -> str: match cmd.split(): case ["quit"]: return "Goodbye" case ["load", filename]: return f"Loading {filename}" case ["move", x, y] if x.isdigit() and y.isdigit(): return f"Moving to ({x}, {y})" case _: return "Unknown command" # zip with strict mode keys = ["a", "b", "c"] values = [1, 2, 3, 4] # This will raise ValueError! combined = dict(zip(keys, values, strict=True)) ``` #### 3.10 → 3.11 | Change | Impact | Action | |--------|--------|--------| | **Up to 60% faster** | Performance | Free performance win | | `ExceptionGroup` and `except*` | Error handling | Migrate grouped exception handling | | `Self` type | Type hints | Use for return-type annotations | | `tomllib` | Stdlib | Remove `tomli` dependency | | `TaskGroup` (asyncio) | Async | Use for structured concurrency | | Type parameter syntax | Type hints | New `class MyClass[T]:` syntax | | `contextlib.chdir()` | File ops | Replace os.chdir patterns | ```python # TOML parsing (no more external dependency) import tomllib # Python 3.11+ with open("pyproject.toml", "rb") as f: config = tomllib.load(f) # TaskGroup for structured concurrency import asyncio async def fetch_all(): async with asyncio.TaskGroup() as tg: task1 = tg.create_task(fetch_users()) task2 = tg.create_task(fetch_orders()) # Both tasks are done here # New type parameter syntax from typing import Self class LinkedList: def copy(self) -> Self: ... # Type parameter syntax from typing import TypeVar # BEFORE: T = TypeVar('T', bound=int) # AFTER: class Stack[T]: def push(self, item: T) -> None: ... def pop(self) -> T: ... ``` #### 3.11 → 3.12 | Change | Impact | Action | |--------|--------|--------| | **Up to 25% faster** (on top of 3.11) | Performance | Another free win | | `type` statement (PEP 695) | Type hints | Replace TypeVar usages | | `f-string` improvements | DX | Nested quotes, comments, expressions | | `buffer` protocol | C extension | Review C extension code | | `subprocess` improvements | CLI tools | Review subprocess usage | | `itertools.batched()` | Utilities | Use for batching | | Better error messages | DX | Update error pattern tests | | `perf` profiler built-in | Profiling | Replace external profilers | ```python # New type parameter syntax (PEP 695) # BEFORE: from typing import TypeVar, Generic T = TypeVar('T') class Box(Generic[T]): def __init__(self, item: T): self.item = item def get(self) -> T: return self.item # AFTER (Python 3.12): class Box[T]: def __init__(self, item: T): self.item = item def get(self) -> T: return self.item # Improved f-strings f"{'hello world'!upper}" # Nested quotes! f"{x=}" # Debug expressions f"result: {x if x > 0 else 0}" # More flexible # itertools.batched from itertools import batched for batch in batched(range(10), 3): print(batch) # (0,1,2), (3,4,5), (6,7,8), (9,) ``` **Breaking Change Detection Patterns (Python):** ```bash # Check for removed/deprecated patterns grep -rn "typing.Union\|typing.Optional\|typing.List\|typing.Dict" src/ # Can use built-in types grep -rn "from __future__ import annotations" src/ # May no longer be needed grep -rn "import tomli" src/ # Replace with tomllib (3.11+) grep -rn "distutils" src/ # Removed in 3.12 grep -rn "imp module\|import imp" src/ # Long removed grep -rn "asyncio.get_event_loop()" src/ # Deprecation warnings in 3.10+ # Check Python version pins grep -rn "python-version\|python_version\|_requires_python" setup.py setup.cfg pyproject.toml ``` --- ### 4. TypeScript 4 → 5 #### Major Changes in TS 5.0 | Change | Impact | Action | |--------|--------|--------| | Decorators (Stage 3) | New feature | Migrate from `experimentalDecorators` to standard decorators | | `const` type parameters | Performance | Use for literal inference | | `--verbatimModuleSyntax` | Config | Replace `--isolatedModules` for ESM/CJS | | `enum` improvements | Config | All enums are union enums by default | | JSDoc `@satisfies` | Documentation | Type-check without widening | | Export type `*` | Imports | Use `export type *` for type-only re-exports | | `--moduleResolution bundler` | Config | For bundler-based projects | #### TS 5.0 → 5.4+ | Change | Impact | Action | |--------|--------|--------| | `NoInfer` utility | Type safety | Prevent unwanted type inference | | `Object.groupBy` / `Map.groupBy` | Utilities | Use for grouping operations | | Variable narrowing in closures | DX | Fewer type assertions needed | | `satisfies` operator (5.0) | Type safety | Use for precise type checking | | `using` / `Symbol.dispose` | Resource management | Use for automatic cleanup | ```typescript // BEFORE (TS 4): Decorators "experimentalDecorators": true @testable class MyClass { } // AFTER (TS 5): Standard decorators (Stage 3) function logged(originalMethod: any, context: ClassMethodDecoratorContext) { // ... } class MyClass { @logged myMethod() { } } // const type parameters function createRoute<const T extends string>(paths: T[]) { return paths; // Inferred as literal types, not string[] } const routes = createRoute(["/home", "/about"]); // readonly ["/home", "/about"] // satisfies operator (TS 4.9+) const config = { port: 3000, host: "localhost", } satisfies Record<string, string | number>; // config.port is typed as number, not string | number // NoInfer function createMachine<T>(options: { states: T[]; initialState: NoInfer<T>; }) { /* ... */ } // grouped const grouped = Object.groupBy(items, item => item.category); ``` **Breaking Change Detection Patterns (TypeScript):** ```bash # Check experimental decorators usage grep -rn "experimentalDecorators" tsconfig*.json # Check module resolution settings grep -rn "moduleResolution" tsconfig*.json # Check for outdated type patterns grep -rn ": any\b" src/ --include="*.ts" --include="*.tsx" # Check tsconfig settings that changed defaults grep -rn "strict\|noImplicitAny\|isolatedModules" tsconfig*.json # Check for enum patterns grep -rn "enum " src/ --include="*.ts" ``` **tsconfig.json Migration:** ```jsonc { // Recommended TS 5.x settings "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", // or "node16" / "nodenext" "verbatimModuleSyntax": true, // replaces isolatedModules "strict": true, "skipLibCheck": true, "noUncheckedIndexedAccess": true, "noPropertyAccessFromIndexSignature": true // Remove: "experimentalDecorators": true (use standard decorators) } } ``` --- ### 5. Next.js 13 → 14 → 15 #### 13 → 14 | Change | Impact | Action | |--------|--------|--------| | App Router stable | Paradigm shift | Migrate from Pages Router | | Server Actions stable | New API | Replace API routes for mutations | | Turbopack (stable for dev) | Performance | Enable in next.config | | Partial Prerendering (experimental) | Performance | Evaluate for mixed pages | | Metadata API | Config | Replace Head component usage | ```typescript // BEFORE (Pages Router): pages/index.tsx export default function Home({ data }) { return <div>{data}</div>; } export async function getServerSideProps() { const data = await fetchData(); return { props: { data } }; } // AFTER (App Router): app/page.tsx export default async function Home() { const data = await fetchData(); // Direct async component return <div>{data}</div>; } // Server Actions // app/actions.ts 'use server'; export async function createPost(formData: FormData) { const title = formData.get('title'); await db.posts.create({ data: { title } }); revalidatePath('/posts'); } // app/components/NewPost.tsx import { createPost } from '../actions'; export function NewPost() { return ( <form action={createPost}> <input name="title" /> <button type="submit">Create</button> </form> ); } // Metadata API // BEFORE: import Head from 'next/head'; <Head><title>My Page

``` **Breaking Change Detection Patterns (Tailwind):** ```bash # Check for v3-specific patterns grep -rn "bg-opacity-\|text-opacity-\|border-opacity-" src/ grep -rn "@screen " src/ # Removed in v4 grep -rn "tailwind.config" . # Config migration needed grep -rn "darkMode:" tailwind.config.js # New default behavior grep -rn "plugins:" tailwind.config.js # Most plugins may need update grep -rn "@tailwind" postcss.config.js tailwind.config.js # PostCSS setup grep -rn "@apply" src/ # Review each usage grep -rn "purge\|content:" tailwind.config.js # Auto-detection in v4 ``` --- ## Dependency Upgrade Strategy ### Semantic Versioning Rules ``` MAJOR.MINOR.PATCH │ │ └── Backward-compatible bug fixes → Always safe │ └─────── Backward-compatible new features → Usually safe └──────────── Breaking changes → Read changelog, plan migration ``` ### Upgrade Order 1. **Dev dependencies first** (linters, test frameworks, type definitions) 2. **Peer dependencies next** (TypeScript before React, React before React-Router) 3. **Runtime dependencies last** (libraries your app imports) 4. **One major version at a time** (Don't jump from v2 to v5 directly) ### Lockfile Management ```bash # Node.js npm ci # Install from lockfile (CI) npm update # Update within semver range npx npm-check-updates # Check what's available npx npm-check-updates -u # Update package.json (not lockfile) # Python pip install --upgrade pip freeze > requirements.txt # Regenerate # Or with pip-tools: pip-compile requirements.in # Generate lockfile pip-sync requirements.txt # Sync environment # Always commit lockfile changes: git add package-lock.json pnpm-lock.yaml yarn.lock requirements.txt git commit -m "chore: update lockfile after dependency upgrade" ``` ### Testing After Upgrades ``` 1. Run linter → npx eslint src/ (or ruff check .) 2. Run type check → npx tsc --noEmit 3. Run unit tests → npm test (or pytest) 4. Run build → npm run build 5. Run e2e tests → npx playwright test 6. Manual smoke test → Start the app, click around ``` --- ## Backward Compatibility Checker ### Common Breaking Change Patterns ``` Pattern | Technologies | Severity ─────────────────────────────────┼─────────────────────┼───────── Function renamed/removed | All | HIGH Default export changed | JS/TS | HIGH Config file format changed | All | MEDIUM CLI flags renamed | CLI tools | MEDIUM API response shape changed | REST/GraphQL | HIGH Environment variable renamed | All | MEDIUM File/directory structure changed | Frameworks | HIGH Peer dependency version bumped | npm/pip | HIGH CSS class names changed | UI libraries | MEDIUM Behavioral change (implicit) | All | CRITICAL Node.js engine requirement | npm packages | MEDIUM Python version requirement | pip packages | MEDIUM Docker base image removed | Docker | HIGH ``` ### Automated Compatibility Scan ```bash # Node.js project scan echo "=== Dependency Version Check ===" npx npm-check-updates 2>/dev/null || echo "npm-check-updates not available" echo "=== Deprecated API Usage ===" # React grep -rn "ReactDOM.render\|findDOMNode\|defaultProps\|String refs" src/ 2>/dev/null # Node.js grep -rn "require(\|module.exports\|__dirname" src/ 2>/dev/null # General grep -rn "deprecated\|@deprecated\|TODO.*remove\|HACK" src/ 2>/dev/null echo "=== Type Safety ===" npx tsc --noEmit 2>&1 | head -20 echo "=== Outdated Dependencies ===" npm outdated 2>/dev/null | head -20 ``` --- ## Migration Cost Estimator ### Effort Matrix ``` Migration Type | Effort | Risk | Downtime ────────────────────────┼───────────┼──────────┼───────── Patch version upgrade | 0.5-1h | LOW | None Minor version upgrade | 1-4h | LOW-MED | None Major version upgrade | 4h-3d | MEDIUM | Planned Multi-major jump | 1-5d | HIGH | Planned Framework migration | 2-10d | HIGH | Planned Language version bump | 1-3d | MEDIUM | Planned Full stack upgrade | 1-4 weeks | CRITICAL | Staged ``` ### Risk Factors | Factor | Low Risk | Medium Risk | High Risk | |--------|----------|-------------|-----------| | Test coverage | >80% | 40-80% | <40% | | Documentation | Good changelog | Minimal | None | | Breaking changes | <5 | 5-20 | >20 | | Dependencies affected | <10 | 10-50 | >50 | | Team familiarity | Used to upgrades | Some experience | First major upgrade | | Rollback capability | Easy (git) | Possible | Hard (DB schema) | ### Cost Estimation Prompt When a user asks for a migration estimate, provide: 1. **Effort range** (hours/days) based on the matrix above 2. **Risk level** based on the risk factors 3. **Recommended approach** (phased vs big bang) 4. **Prerequisites** (tests, backups, staging environment) 5. **Timeline** with milestones --- ## Rollback Planning ### Pre-Migration Checklist ``` □ Full backup of codebase (git tag: pre-migration--v) □ Full database backup (if applicable) □ All tests passing on current version □ Deployment pipeline green □ Staging environment available □ Team notified of planned maintenance window □ Rollback plan documented and tested □ Monitoring/alerting configured ``` ### Rollback Procedures #### Git-Based Rollback (Recommended) ```bash # If migration goes wrong: git tag pre-migration-react-18 # ... do migration ... # Rollback: git checkout main git reset --hard pre-migration-react-18 git push --force # Only if no one else pushed # Better: revert merge git revert -m 1 ``` #### Database Rollback ```bash # Before migration: pg_dump dbname > backup-$(date +%Y%m%d).sql # After failed migration: psql dbname < backup-20240101.sql ``` #### Docker Rollback ```bash # Pin to specific image version docker tag myapp:latest myapp:backup-$(date +%Y%m%d) docker pull myapp:previous-version docker compose up -d ``` #### npm/pip Rollback ```bash # npm npm install @ npm audit fix # pip pip install == pip freeze > requirements.txt ``` ### Technology-Specific Rollback Notes | Technology | Rollback Difficulty | Notes | |------------|-------------------|-------| | React | Easy | Component-level, can mix old/new | | Node.js | Easy | Version manager (nvm/fnm) | | Python | Easy | Version manager (pyenv) | | TypeScript | Easy | Revert config + reinstall | | Next.js | Medium | App Router changes are structural | | Docker | Easy | Pin image tags | | Tailwind CSS | Medium | CSS changes may cascade | --- ## Testing Strategy ### Pre-Migration Testing ``` 1. Ensure ALL tests pass on current version 2. Add integration tests for critical user flows 3. Snapshot current test coverage: npm test -- --coverage 4. Record baseline performance metrics 5. Test the migration on a feature branch first ``` ### During Migration Testing ``` After each migration step: □ Run linter □ Run type checker □ Run unit tests □ Run build □ Run integration tests □ Quick manual smoke test If any step fails: → Investigate → Fix if trivial (< 15 min) → Rollback if non-trivial → Document the issue ``` ### Post-Migration Testing ``` 1. Full test suite (unit + integration + e2e) 2. Visual regression testing (if UI changes) 3. Performance benchmarking (compare to baseline) 4. Accessibility testing (if HTML/ARIA changes) 5. Cross-browser testing (if browser APIs changed) 6. Load testing (if runtime changed, e.g., Node.js version) 7. Security scan (npm audit / pip audit) ``` ### Test Priority Matrix | Test Type | Priority | When | |-----------|----------|------| | Unit tests | P0 | Every step | | Type checking | P0 | Every step | | Build | P0 | Every step | | Integration tests | P1 | After each phase | | E2E tests | P1 | Before merge | | Performance tests | P2 | After full migration | | Visual regression | P2 | If UI framework changed | | Security scan | P1 | Before merge | --- ## Migration Report Generator After completing a migration, generate a structured report: ### Report Template ```markdown # Migration Report: → **Date:** YYYY-MM-DD **Status:** ✅ Success / ⚠️ Partial / ❌ Failed ## Summary - **Scope:** files changed, dependencies updated - **Duration:** - **Risk Level:** → - **Test Coverage:** → ## Changes Made ### Dependencies Updated | Package | From | To | Type | |---------|------|----|------| | react | 17.0.2 | 18.2.0 | major | ### Code Changes | File | Change | Status | |------|--------|--------| | src/index.tsx | Replace ReactDOM.render with createRoot | ✅ | | src/App.tsx | Update useEffect for batching | ✅ | ### Configuration Changes | File | Change | |------|--------| | tsconfig.json | Updated moduleResolution to bundler | | package.json | Added type: "module" | ## Issues Encountered 1. **Issue:** - **Resolution:** - **Time spent:** ## Test Results - **Before migration:** 142/142 passing, 87% coverage - **After migration:** 145/145 passing, 89% coverage - **New tests added:** 3 (for new APIs) ## Performance Impact - **Build time:** 12s → 8s (33% faster) - **Bundle size:** 245KB → 238KB (3% smaller) - **Runtime:** No measurable change ## Rollback Status - **Rollback tested:** Yes/No - **Rollback time:** - **Data loss risk:** None ## Recommendations 1. 2. 3. ``` ### Generating the Report After completing a migration, review all git commits in the migration branch to auto-populate the report: ```bash # Generate list of changed files git diff --stat main...migration/branch # Generate commit summary git log main...migration/branch --oneline # Check test results npm test -- --coverage 2>&1 | tail -20 # Build time comparison time npm run build ``` --- ## Quick Reference ### One-Liner Migration Checks ```bash # "Should I upgrade this dependency?" npm view versions --json | tail -5 npm view dist-tags # "What changed between these versions?" npm view @ --json 2>/dev/null | grep -E "version|deprecated|peerDependencies" # "Is this package still maintained?" npm view time --json 2>/dev/null | tail -3 ``` ### Emergency Commands ```bash # Last known good state git stash && git checkout main # Rollback a specific package npm install @ # Nuclear option (careful!) rm -rf node_modules package-lock.json && npm install # Python equivalent pip install == ``` --- ## Anti-Patterns to Avoid 1. ❌ **Upgrading everything at once** — One thing at a time, verify each step. 2. ❌ **Skipping tests** — "I'll test it later" = "I'll debug it in production." 3. ❌ **Ignoring peer dependency warnings** — They exist for a reason. 4. ❌ **Force-resolving conflicts** — Understand the conflict before forcing a resolution. 5. ❌ **Not reading the changelog** — Changelogs contain migration guides and breaking changes. 6. ❌ **Forgetting lockfiles** — Always commit lockfiles; they ensure reproducible builds. 7. ❌ **No rollback plan** — Always have a way back. Always. 8. ❌ **Upgrading on Friday** — Monday's problem, your weekend's anxiety. 9. ❌ **Ignoring deprecation warnings** — Today's warning is tomorrow's breaking change. 10. ❌ **Not testing in staging** — Production is not a test environment.