So You've Decided To Do a Technical Migration

Sophie Koonin discusses the realities of large-scale technical migrations, using Monzo's shift to TypeScript as a roadmap. She explains how to handle "bends in the road," from documentation and tooling to setting measurable milestones. Sophie shares vital lessons on balancing technical debt with feature work and provides a framework for deciding if a migration is truly worth the effort.

The Reality of Technical Migrations

Sophie Koonin opens with a stark truth: migrations are hard. What seems like a straight path to improvement often becomes an uphill journey full of twists, turns, and unexpected challenges. Using Monzo's two-year TypeScript migration as a case study, she outlines the practical realities teams face when undertaking major technical changes.

Monzo's Migration Journey

Monzo, a mobile-first bank based in London, faced a critical decision when their Flow-based type system became increasingly difficult to maintain. Flow, Facebook's JavaScript type checker, had served them well initially, but by 2021 it was clear they'd backed the wrong horse. The public fork was poorly maintained, third-party library support was dwindling, and the Flow server crashed constantly during development.

TypeScript had become the de facto standard for static typing in JavaScript, with massive community support and Microsoft backing. The decision to migrate wasn't taken lightly, but the writing was on the wall.

Starting Small and Proving Value

Rather than jumping straight into a full migration, Koonin emphasizes starting with small experiments. A couple of engineers created a side project to test whether migrating a single package to TypeScript was even feasible. This approach served multiple purposes:

• Proved the concept before seeking organizational buy-in
• Identified potential roadblocks early
• Built confidence in the migration path
• Created a foundation for documentation

"Without a really clearly defined plan and timeline, you're asking people with very little context to let you focus on what they might see as less important maintenance work over prioritized teamwork," Koonin explains.

Documentation as a First-Class Citizen

From day one, the team treated documentation as essential infrastructure. They created a comprehensive Notion space covering:

• Why the migration was necessary
• How the migration would work
• What milestones they were targeting
• Who to contact with questions

This documentation proved invaluable when Koonin returned to Monzo after a year away and needed to quickly understand the project's status and approach.

Tooling: The Unsung Hero

Koonin stresses that tooling makes or breaks migrations. Manual processes simply don't scale. Monzo developed several key tools:

• A command-line migration script that automated much of the conversion
• A package generator that created new libraries in TypeScript by default
• Scripts to identify which packages were ready to migrate based on dependency status
• A dashboard tracking migration progress across the monorepo

"If we'd done this all manually, it would have taken twice, three times as long. Lean on tooling as much as you humanly can," she advises.

The Incremental Approach

The team chose an incremental migration strategy, spreading the work across multiple teams rather than dedicating a single team to the effort. This decision came with trade-offs:

Pros:

• No need to ring-fence one team for an extended period
• Lower organizational risk
• Teams could work at their own pace

Cons:

• Significantly longer timeline
• Dependent on individual team priorities
• Risk of losing momentum

To combat the risk of losing momentum, they implemented monthly progress updates and celebrated teams that migrated the most packages each month.

Setting Measurable Milestones

Progress tracking became crucial for maintaining morale and communicating with stakeholders. The team created a dashboard showing the ratio of Flow packages to TypeScript packages, celebrating when the lines finally crossed over.

They established clear milestones:

• First app migrated
• Business banking web app migrated
• BizOps (customer service app) migrated

These milestones helped break down the massive project into digestible chunks and provided regular opportunities to celebrate progress.

Getting and Maintaining Buy-In

Early in the project, buy-in wasn't a major concern because Monzo's culture encouraged "discipline work"—maintenance and improvement tasks alongside feature development. However, as the migration dragged on, maintaining organizational support became critical.

Koonin's approach to securing buy-in included:

• Clearly articulating current problems and expected benefits
• Understanding what different stakeholders cared about (risk, cost, velocity)
• Setting a hard deadline with engineering leadership support
• Breaking remaining work into tickets assigned to specific teams
• Monthly progress reports and celebrations

The Risk of Unfinished Migrations

One of the most compelling parts of Koonin's talk addresses the danger of incomplete migrations. She warns that starting a migration without finishing it can leave you worse off than before:

• Multiple competing technologies create confusion
• Engineers don't know which approach to use
• Maintenance burden increases
• User experience suffers from larger bundle sizes

"The greatest threat to any migration is not complexity, it's actually changing organizational priorities that leave you unable to finish," she states.

Safety and Rollback Planning

Even for relatively low-risk migrations like type system changes, safety planning is essential. Monzo established:

• Guardrails with defined rollback triggers
• Side-by-side monitoring dashboards for old and new systems
• Clear rollback procedures documented for anyone to follow
• Shadow mode testing where possible

For higher-risk migrations, they've used pilot programs with small groups of users and proportional traffic routing to validate changes before full rollout.

Celebration and Recognition

The team celebrated their completion with stickers, cupcakes, and public recognition. Koonin emphasizes that acknowledging the effort and achievement is crucial for team morale and organizational learning.

Should You Do a Migration?

Koonin provides a framework for evaluating whether a migration is worth undertaking:

Ask first: Do you need to do this at all?

• Will you be worse off if you don't migrate?
• Is the benefit worth the developer hours required?
• Is there a point where effort outweighs value?

Consider maintenance costs:

• Who will maintain the new technology?
• Does more than one person understand it?
• Are you prepared for major version upgrades?
• Can you hire people with these skills?

Evaluate your motivations:

• Are you following industry trends without clear need?
• Is this just different or actually better?
• Are you holding yourself back by avoiding new technologies?

Remember: Boring is often better

• Familiar technologies are easier to maintain
• Large communities provide better support
• Documentation and learning resources are more abundant
• Reliability often trumps novelty

Key Takeaways

1. Start small and prove value before seeking organizational buy-in
2. Document everything from the beginning—future engineers will thank you
3. Invest heavily in tooling to automate repetitive tasks
4. Set measurable milestones to track progress and maintain morale
5. Get stakeholder buy-in by clearly articulating problems and benefits
6. Plan for the risk of not finishing and communicate this clearly
7. Establish safety measures and rollback procedures
8. Celebrate completion and recognize everyone involved
9. Carefully evaluate whether a migration is truly necessary
10. Don't be afraid of boring technology if it solves your problems

Koonin's talk provides a comprehensive framework for approaching technical migrations, whether you're moving to TypeScript, upgrading major dependencies, or replatforming entire systems. The lessons learned at Monzo apply broadly to any organization facing the challenge of evolving their technology stack while maintaining business continuity.