Migrations rarely finish

In my experience working on platform teams, I've rarely been able to fully complete a migration from one pattern to another. There are always edge cases, teams with other priorities, and code that's harder to move than expected. At some point, momentum stalls and the migration sits at 80% done for months.

This is a normal outcome. Accepting it changes how you approach the work.

Set up backstops first

Instead of starting a migration by rewriting existing code, I've learned to start by setting up backstops. A backstop is a mechanism that prevents new code from using the old pattern. It doesn't fix the existing codebase, but it stops the problem from getting worse.

In practice, this is usually a lint rule. If you're migrating from one component to another, write a lint rule that flags imports of the old component. If you're moving from one API pattern to another, lint against the old one. The goal is to make the old pattern harder to use than the new one.

Why backstops come first

If you start by migrating existing code without a backstop in place, you're filling a bathtub with the drain open. Engineers who don't know about the migration will keep writing code that uses the old pattern. By the time you've migrated 50 files, 10 new ones have appeared.

Setting up the backstop first means that even if the migration stalls, at least the problem isn't growing. Every new file uses the new pattern. The old code becomes a fixed-size problem instead of an expanding one.

The migration becomes optional

Once the backstop is in place, you have breathing room. You can chip away at the remaining old code incrementally, prioritize it against other work, or even hand off codemods to product teams to help with the effort. The backstop bought you time by guaranteeing that the situation won't regress.

The best platform engineering work isn't always about finishing migrations. Sometimes it's about making sure you never have to start the same migration twice.

For an extremely advanced example of this concept in practice, check out Notion's write-up on their ratcheting system using custom ESLint rules.