Two migrations that both worked

On a Sunday in March 2022, Stripe converted the codebase behind the Stripe Dashboard from Flow, Meta's type checker for JavaScript, to TypeScript. In its engineering post, Stripe reports: "In a single pull request, we converted more than 3.7 million lines of code." The team locked its monorepo, the shared repository that holds the Dashboard code, that morning, took a final quality assurance (QA) pass over the branch and merged.

Twitch went the other way. Its account of breaking up its Ruby on Rails monolith describes a company-wide campaign, begun in 2015, "to move all of Twitch's backend code into Go microservices." A reverse proxy built on NGINX (an open-source web server) sent a share of traffic to a new application programming interface (API) edge written in Go, endpoint by endpoint. The work engaged backend engineers from 2016 to 2018. By the end of 2018 all traffic had left the monolith, and the post adds: "It would still take another year to fully clean up the account of dependencies and access roles."

Both teams finished. Neither account is a controlled comparison, and neither proves its strategy is better. Read together, they help explain each choice.

Fowler's warning is about rewrites

The incremental pattern takes its name from Martin Fowler's Strangler Fig Application entry, first published as "Strangler Application." The new system grows around the old one and takes over its behavior piece by piece. Fowler's case against the alternative is blunt. Teams plan to build a new system that does exactly what the old one does, "But we've seen this simple-sounding plan go down in flames most of the time."

That warning targets a rewrite: people re-implementing behavior nobody has fully specified, while users wait for features. Stripe did not rewrite anything. A codemod, a program that rewrites source code mechanically, translated the Flow code to TypeScript. Stripe spent several months extending a codemod Airtable had published until it handled the Dashboard's edge cases. It had also read accounts from Airtable and Zapier, which had each run a converter over their whole codebase and "merged the output as a single commit." The big-bang step was a machine translation, checked by tests and manual QA.

Fowler names the price of his own pattern too: transitional architecture, "code that will go away once the modernization is complete." He judges that "the reduced risk and earlier value from the gradual approach outweigh its costs." That judgment holds when coexistence is cheap. Stripe's post explains a case where it was not.

The four factors that decide it

Stripe's section on choosing a strategy gives its reasons in three sentences. "The Dashboard codebase has tight coupling between disparate components and no cleanly factored dependency graph." An incremental migration "would force developers to work in both languages to accomplish common tasks." And the team "would also need an interoperability layer to sync type definitions between both languages." Add the question of whether the target can run beside the source at all, and you have four factors:

FactorPoints to big-bangPoints to strangler
CouplingNo clean seams; most changes touch many components (Stripe's Dashboard)Separable units with their own traffic, such as endpoints (Twitch)
ToolingA codemod or compiler can translate the whole codebaseThe target needs new code written by people
Cost of coexistenceDevelopers would work in two languages and keep an interoperability layer in syncA proxy or adapter keeps the two sides apart at low cost
Target compatibilityOld and new cannot run side by side without extra machinery: a file is checked by Flow or by TypeScript, not bothOld and new can each serve live traffic, with a proxy choosing between them

The factors apply per boundary, not per company. Stripe itself handled one piece incrementally. Sail, its shared design system of React components, stayed in Flow while the team generated TypeScript definitions for it and wrote tests to keep the two in step. The post calls that approach "too cumbersome for a large codebase" and says it worked for Sail because "the Sail component interface is explicit and quite rigid." One interface with clean seams went incremental, and the tightly coupled application around it went all at once.

Grab's 2016 Rails to Go migration shows the same test from the other side. Its rollout write-up explains why it did not switch the Domain Name System (DNS) record for its public API to the new server in one step. The Go server would have had to be "coded, tested and configured with perfect foresight" to take all passenger app traffic across more than 30 endpoints at once. The endpoints were separable, so the team shadowed each one, sending copies of live requests to the Go server without returning its responses, and then moved them one by one.

Incremental is not always safer

A strangler migration spreads risk over time instead of removing it. Twitch's post lists what the long middle cost. Developers "had to write code in multiple repositories with different deploy cycles to deliver a single feature." After a 2017 mobile release overloaded the API, the team found that "no one had the responsibility to verify that the two parts worked well together." Retiring the last monolith endpoints meant guessing who still called them: "The only way to tell if it was safe to shut them down was to force 10 minutes of downtime and see if anyone would complain."

Stripe concentrated its risk into one planned day, and the post does not pretend the day was safe: "we were mutating every file in the codebase." The Dashboard had limited end-to-end test coverage, so product teams ran manual tests, which caught a bug that stopped translations loading for non-English users.

Stripe paid in other ways too. Hundreds of engineers contribute to the Dashboard each week, so the team merged on a Sunday with the monorepo locked. It disabled some custom lint rules to restore later, and it accepted 37,000 TypeScript error suppressions, down from more than 97,000 on the first pass, against roughly 5,000 in the Flow code. Tests passed, and the team reports "no unpleasant surprises" as traffic shifted to the new code.

Neither strategy is the cautious one by default. A big-bang change that goes wrong does so on a known day, with the whole team watching. A strangler migration can go wrong quietly for years: a feature built in the wrong stack, a call that skips the adapter, an endpoint nobody owns. When a tool can do the translation and coupling makes coexistence expensive, the atomic change can carry less total risk.

What each choice leaves to govern

The two strategies produce different decisions to keep. A big-bang migration needs one decision after the switch: the old form does not come back. Stripe's suppressions are a known backlog, and the risk is new code that reintroduces the retired pattern, from a branch opened before the switch or an old example. A strangler migration needs a set of transitional decisions, each scoped to the paths it governs and each with a condition that retires it. ADRs for software migrations covers how architecture decision records (ADRs) carry legacy, target and transitional states. Strangler-fig migrations covers keeping new code from reaching past the compatibility adapter while the boundary moves.

The choice itself is a decision, and it rarely gets written down. Record which of the four factors you assessed and what you found. If coupling drove a big-bang choice, the next team can check whether the coupling still exists before it plans the next migration. Migrating from Node.js to Go works through the decisions that a language migration has to keep, including who authorizes each cutover. Coding agents change the tooling factor. Our reading is that cheaper translation pushes some migrations toward a single conversion, while AI-assisted migrations raise the drift risk on the incremental side, where agents copy whichever stack sits nearest.

Once the follow-on decisions are written down, something has to check new code against them. Mneme, an open-source decision and control layer for agentic software development, can enforce part of either outcome today. It enforces only decisions that carry an active typed rule, a machine-checkable constraint attached to the decision and switched on. A rule matches exact literal text, optionally limited to paths.

After a Flow to TypeScript switch, for example, a rule can forbid the @flow pragma (the comment at the top of a file that turns Flow checking on) under the converted application's paths. During a strangler migration, a rule can forbid the legacy package's import path in the new tree, with the adapter excluded.

When Claude Code, Codex CLI (OpenAI's command-line coding agent) or Kiro CLI 3.0 (the command-line version of Amazon's Kiro agent) edits a file through its own editing tools, Mneme checks the change before the file is saved. Continuous integration (CI) checks pull requests. Each result is PASS, WARN or FAIL, and a violation names the decision it broke. The Decision Index, Mneme's persisted, versioned record of decisions, keeps each decision's versions, lifecycle status and source. It does not record who approved a decision, so keep that approval in review.

Mneme does not choose the strategy, score coupling or prove that a converted codebase behaves like the original. Your tests, codemod and deployment tools answer those questions. Keeping the chosen strategy's decisions in force afterwards is part of engineering decision governance.

What engineering leaders should do

  • Separate translation from rewriting. Fowler's warning is about people re-implementing behavior. A tool-driven conversion carries different risks, which you test for in QA and production monitoring.
  • Price coexistence before you choose. Count the interoperability layers, the dual-language work and the years of transitional code, the way Stripe did.
  • Decide per boundary. A rigid interface can migrate incrementally inside a codebase that moves all at once.
  • Write the choice down with its factors, then write the follow-on decisions: no reintroduction after a big-bang switch, scoped transitional decisions with retirement conditions during a strangler migration.

Frequently asked questions

What is the difference between a strangler and a big-bang migration?+
A strangler migration, named after Martin Fowler's Strangler Fig Application entry, moves behavior from the old system to the new one piece by piece while both run. A big-bang migration switches everything in one change. Twitch moved its backend to Go microservices endpoint by endpoint between 2016 and 2018; Stripe converted more than 3.7 million lines from Flow to TypeScript in a single pull request.
Why did Stripe migrate to TypeScript all at once?+
Stripe's 2022 post gives three reasons: the Dashboard codebase had tight coupling and no cleanly factored dependency graph, an incremental migration would have made developers work in both languages for common tasks, and the team would have needed an interoperability layer to keep type definitions in sync. A codemod made the one-step conversion possible.
Is an incremental migration always safer?+
No. It spreads risk over the coexistence period. Twitch reports features that needed code in several repositories, an overload in 2017 where nobody owned checking that the two parts worked together, and a year of cleanup after traffic left the monolith. When a tool can translate the code and coexistence is expensive, a single planned switch can carry less total risk.
What should be governed after a big-bang migration?+
Mainly that the retired pattern does not return, plus any deferred work such as Stripe's 37,000 error suppressions. Mneme can enforce a no-reintroduction decision when it carries an active typed rule, which matches exact literal text such as a Flow pragma, optionally limited to paths. It does not prove the converted code behaves like the original; tests do that.