Most migration plans start with the target state. Practical migration checklists should start with rollback.
The target architecture is the easy part to describe. The harder question is what happens when the new path fails halfway through, or when it works technically but creates unacceptable user impact.
Rollback clarifies the real shape of the migration
When rollback is vague, the migration is usually vague too.
If rollback is “restore the old system”, ask:
- Which data changed while the new system was active?
- Can the old system still read that data?
- Which DNS, queue, cron, or routing changes need to be reversed?
- How will we know the rollback is complete?
- Who is allowed to make the call?
These questions expose the real coupling. They also make the migration smaller because every irreversible step becomes visible.
A useful checklist has phases
I prefer migration checklists that separate work into phases:
- Preparation: backups, access, inventory, baseline metrics.
- Dry run: prove the steps without touching production traffic.
- Cutover: the smallest change that moves real traffic.
- Verification: user-visible checks, logs, metrics, and data consistency.
- Rollback: exact commands and conditions.
- Cleanup: remove old paths only after confidence is earned.
The cleanup phase should not happen in the same breath as the cutover. Keeping the old path around for a short, intentional window is often cheaper than pretending every migration is final.
The best checklist is executable by someone tired
Migration work often happens when people are already under load. The checklist should be plain enough that another engineer can follow it without reconstructing the whole design in their head.
Good checklists include:
- Preconditions.
- Commands or links to the source of commands.
- Expected outputs.
- Stop conditions.
- Verification steps.
- Rollback steps.
A migration checklist is not paperwork. It is an operating tool for a risky moment.