migrate-framework

Migrate Framework

Migrate incrementally — never change more than one batch without running tests.

Workflow

Survey → Plan → Migrate → Verify → Clean up

1. Survey

Map the migration surface:

tl parallel \
  "structure=tl structure" \
  "search=tl search '<old-api-pattern>'" \
  "stack=tl stack"
tl context7 <framework> "migration guide" -t 5000  # Official migration path
# Or: tl browse <migration-guide-url>

2. Plan

Group the work into safe increments:

tl parallel "impact=tl impact <file>" "related=tl related <file>"

Order: leaf files (0 dependents) first, shared utilities last. Each increment must leave the codebase in a working state.

3. Migrate

One batch at a time:

tl symbols <file>          # Know the shape before modifying
tl snippet <function> <file>   # Read each usage site
# Apply the migration pattern from the guide
tl diff --breaking         # Catch accidental API changes after each batch

4. Verify

After every batch, not at the end:

tl parallel \
  "test=tl run '<test command>'" \
  "guard=tl guard" \
  "exports=tl exports <file>"
# Commit after each passing batch

5. Clean up

Remove old-world artifacts:

tl parallel \
  "search=tl search '<old-api-pattern>'" \
  "unused=tl unused" \
  "deps=tl deps <file>"

Decision tree

Migration request → How big is the surface?
  ├─ Small (<10 usages) → Single batch
  │   → tl search to find all, migrate, tl run tests
  ├─ Medium (10-50 usages) → Batch by directory
  │   → tl related to group files
  │   → Migrate + test one directory at a time
  │   → Commit after each batch
  └─ Large (50+ usages) → Batch by dependency order
      → tl impact to sort files by dependents
      → Leaf files first, shared modules last
      → Migrate + test + commit per batch
      → tl search "<old-pattern>" to track remaining count

Tips

• Never start migrating without the migration guide — tl context7 or tl browse first
• Commit after each passing batch — if batch 7 breaks, you bisect to batch 7
• Use tl search "<old-pattern>" to track how many usages remain after each batch
• Leaf files first reduces risk — they have no dependents to break
• For large migrations, tl impact output determines the safest execution order