Migration & Refactoring

Systematic approach to complex code migrations with safety guardrails and rollback capabilities.

When to Use

• Dependency upgrades that force source changes - major bumps with breaking APIs; routine patch/minor/CVE bumps go to dependency-upgrades
• Framework migrations - React class→hooks, Flask→FastAPI, Django→DRF, etc.
• Language modernizations - Python 2→3, JavaScript→TypeScript
• Large-scale refactoring - Cross-file changes requiring consistency
• Database schema evolution - Migrations with data transformation
• Monorepo decomposition - Extracting services from monoliths

Core Workflow

Phase 1: Analysis

1. Identify scope - What files, modules, and dependencies are affected?
2. Map dependencies - Create a dependency graph of cross-file relationships
3. Find breaking changes - Analyze changelogs, migration guides, deprecation warnings
4. Assess risk - Flag high-risk changes (public APIs, critical paths)

Phase 2: Planning

1. Create migration plan - Ordered sequence of changes
2. Define checkpoints - Intermediate states that compile/work
3. Design rollback strategy - How to revert if issues arise
4. Estimate effort - Time and complexity assessment

Phase 3: Execution

1. Execute in phases - Apply changes incrementally
2. Validate at each checkpoint - Test compilation, run tests, verify functionality
3. Document changes - Update docs, changelogs, ADRs
4. Commit incrementally - Each checkpoint is a commit

Phase 4: Validation

1. Run full test suite - Verify nothing broken
2. Performance testing - Ensure no regressions
3. Code review - Human validation of changes
4. Production rollout - Deploy with monitoring

Migration Patterns

Pattern 1: Gradual Migration

Old API → Compatibility Layer → New API → Remove Old

When: Cannot change all call sites at once

Pattern 2: Feature Flags

if (useNewImplementation) {
  return newImplementation();
} else {
  return oldImplementation();
}

When: High-risk changes needing rollback capability

Pattern 3: Strangler Fig

Monolith → Proxy → New Service
              → Old Monolith

When: Decomposing monoliths incrementally

Pattern 4: Parallel Implementation

Old System (read-only) → Data Sync → New System (write)

When: Zero-downtime migrations with data changes

See references/migration-patterns.md for detailed implementations.

Breaking Change Analysis

Checklist for Upgrades

• Review CHANGELOG for breaking changes
• Check deprecation warnings in current version
• Identify removed/renamed APIs
• Find changed default behaviors
• Note environment/dependency changes
• Review migration guide if available
• Search for known issues in community

Common Breaking Changes

Cross-File Dependency Tracking

Dependency Graph Elements

• Imports/includes - File A imports File B
• Inheritance - Class A extends Class B
• Interface implementations - Class implements Interface
• Function calls - Function in A calls function in B

Tools by Language

• Python: pydeps, importlab
• JavaScript/TypeScript: dependency-cruiser, madge
• Java: jdeps, classycle
• Go: godepgraph
• Rust: cargo-deps

See references/dependency-analysis.md for detailed usage.

Safety Patterns

Snapshot Testing

# Before migration: capture expected outputs
save_snapshot(test_output, "v1_expected.json")

# After migration: compare
assert_matches_snapshot(actual_output, "v1_expected.json")

Property-Based Testing

# Verify invariants hold post-migration
@given(st.data())
def test_migration_preserves_properties(data):
    old_result = old_implementation(data)
    new_result = new_implementation(data)
    assert old_result.property == new_result.property

Canary Deployments

1. Deploy to 1% of traffic
2. Monitor error rates, latency
3. Gradually increase to 100%
4. Rollback if issues detected

See references/safety-patterns.md for more patterns.

Rollback Strategies

See references/rollback-strategies.md for platform-specific guides.

Examples

React Class to Hooks: componentDidMount/componentWillUnmount → useEffect, componentDidUpdate → useEffect with deps, this.state → useState, this.props → destructured.

Python 2 to 3: 2to3 -w --output-dir=src_py3 src/ then fix imports, print, string handling. See references/language-migrations.md.

Quality Checklist

• Breaking changes documented
• Rollback procedure tested
• All dependencies mapped
• Checkpoints defined and validated
• Test coverage maintained or improved
• Performance regression testing done
• Code review completed
• Documentation updated

See Also

• static-analysis — Linter triage and fix workflows
• code-review-assistant — PR review workflow
• dependency-upgrades — Routine patch/minor/CVE version bumps

Rationalizations

Red Flags

• Starting a migration without a documented rollback strategy
• Migrating multiple major dependencies in a single commit
• Skipping checkpoint validation between migration phases

References

• references/migration-patterns.md - Detailed pattern implementations
• references/dependency-analysis.md - Cross-file dependency tracking
• references/language-migrations.md - Framework migration guides