Code Migration

Code Migration

The Iron Rule

ASSESS BEFORE PLANNING. PLAN BEFORE CODING. TEST BEFORE CUTTING OVER.

Never start migrating code without completing the assessment phase. Skipping assessment leads to mid-migration surprises that blow timelines.

Phase 1: Migration Assessment

Step 1 — Quantify Scope

# Gather hard numbers before estimating anything
find src/ -type f | wc -l                          # Total files
cloc src/ --quiet                                  # LOC by language
grep -r "import\|require" src/ | wc -l             # Dependency touchpoints
find src/ -name "*.test.*" -o -name "*_test.*" | wc -l  # Test coverage proxy

Step 2 — Score Complexity (1–5 per factor)

Total score: Sum ÷ 5 → complexity rating. <2 = simple, 2–3.5 = moderate, >3.5 = complex.

Step 3 — Identify Risk Patterns

Scan the codebase for patterns that cause migration failures:

Step 4 — Produce Assessment Document

## Migration Assessment: [Source] → [Target]

**Complexity Score**: X.X / 5.0
**Estimated Effort**: [range] person-weeks
**Risk Level**: Low / Medium / High

### Scope
- Files affected: N
- LOC to migrate: N
- Dependencies to replace: N (list them)
- Test coverage: X% (measured, not guessed)

### Critical Risks
1. [Risk] — Impact: [what breaks] — Mitigation: [strategy]

### Dependencies Without Direct Equivalents
| Source Dependency | Purpose | Target Replacement | Effort |
|---|---|---|---|

### Unresolved Questions
- [List every ambiguity — do NOT proceed with assumptions]

If ANY unresolved questions exist: present the assessment and ask before proceeding to Phase 2.

Phase 2: Strategy Selection

Pick ONE strategy. Do not combine them.

Strangler Fig Implementation Pattern

1. Identify a boundary (API endpoint, page, module)
2. Build new version behind the boundary
3. Route traffic/calls to new version
4. Verify equivalence (tests, monitoring, shadow traffic)
5. Remove old version
6. Repeat for next boundary

Phase 3: Migration Plan

Simple Migration (complexity < 2.5)

Complex Migration (complexity ≥ 2.5)

Migration Order

Migrate in dependency order — leaves first, roots last:

1. Utilities / helpers (no internal dependencies)
2. Data models / types
3. Business logic modules
4. Integration layers (APIs, database, external services)
5. UI / presentation layer
6. Configuration and build system

Phase 4: Testing Strategy

Comparison Tests (Write These FIRST)

Before migrating any module, write tests that capture current behavior:

1. Identify public API of the module (functions, endpoints, events)
2. Write tests against the OLD code that assert current behavior
3. Run tests — they must pass on old code
4. Migrate the module
5. Run the SAME tests against new code — they must still pass

This catches behavioral regressions that unit tests miss.

Test Categories

Phase 5: Rollback

Rollback Triggers — Decide These BEFORE Migrating

Rollback Procedures by Strategy

Large-Scale Migration

For large codebases (>50 files affected), organize migration into independent module batches:

1. Group files by module/package — each batch must be independently migratable
2. Process batches sequentially — migrate one module at a time
3. After each batch: run tests, verify no regressions, commit
4. After all batches: run full test suite, verify cross-module interactions

Deliverables Checklist

• Migration assessment with complexity score
• Strategy selection with rationale
• Phased migration plan with timeline
• Comparison tests for each module (written before migration)
• Rollback triggers and procedures defined
• Progress tracking per module

Converted and distributed by TomeVault — claim your Tome and manage your conversions.