On the joy of small migrations

The best refactor I've ever reviewed was 11 lines. It changed a function signature, updated the three call sites, bumped a comment. The PR description was one sentence. It shipped on a Tuesday and nobody noticed, which was the entire point.

Good migrations aren't loud. They're small, they fit in one head at a time, and they happen constantly.

The rituals that let them exist

Small migrations are only possible if the team has a few habits in place. None of them are clever; most of them are unfashionable.

1. Trunk-based development, with real discipline. Long-lived branches accumulate divergence faster than any refactor can fight.
2. A green CI that runs in under 10 minutes. If your test suite is 40 minutes, nobody will ever land a speculative cleanup PR.
3. One clear way to deprecate things. @deprecated with a migration note, not a Slack thread.

Without these, every migration becomes a project. And projects don't land on Tuesdays.

The anti-pattern

The "Big Refactor PR" is the opposite of this. It's usually:

• 2000+ lines
• Touches every module
• Described as "a cleanup"
• Blocks other work for a week
• Gets approved because nobody can review it properly

I've shipped a few of these. Every single one created bugs we didn't catch for weeks. Every single one could have been 10 smaller PRs if anyone had been patient.

The shift in thinking

The mental model I had to unlearn: "I'll do this properly, all at once, so we don't regress."

The model that works: "I'll do this in the smallest slice that makes sense, and accept that the codebase will look weird for a couple of weeks during the migration."

Weird-in-transition is fine. Nobody else reads the codebase during your migration; they read it after. Optimize for the after.

The joy part

The title promised joy. Here it is:

A tiny migration PR is the most satisfying thing to ship. It's small enough to fully understand. It's easy to review. It doesn't break anything. It leaves the codebase a little better than you found it. You can do it on a Tuesday.

Five of those in a year adds up to a codebase that aged well. One "great refactor" adds up to a war story.