A migration checklist for teams that cannot stop shipping
Every migration that failed was attempted in one branch. Here is the shape of the ones that landed.
The failure mode is always the same: a long-lived branch, a moving target, and a merge nobody wants to review. The fix is not better discipline. It is smaller steps that ship.
- Make both versions valid.Old and new must be able to coexist in production, even if that means a temporary shim.
- Move one caller at a time.Every pull request is small enough to revert on its own.
- Delete the shim last.That is the migration, finished. Not the first commit.
It takes longer on paper and finishes sooner in practice, because nothing is ever blocked on a review that takes a week.