Rollback plan
A rollback plan is the written, rehearsed procedure for returning a system to its previous working state after a release goes wrong: which version to restore, how to restore it, what signal justifies it, how data written since the release is handled, and how the team confirms the rollback worked. It is prepared before the release, because the moment it is needed is the worst moment to write it.
The longer version
The plan answers questions in the order they arrive during an incident. What is the trigger: an error rate, a failed smoke test, a specific customer-facing defect. Who calls it: a named person, with a deputy. What is restored, and by which mechanism, whether redeploying the previous artefact, turning off a feature flag, or pointing traffic back at the old instances. What happens to data: whether the schema change is backward compatible, whether records written by the new version are readable by the old one, and whether a migration has to be reversed. How it is verified: the same smoke test that verified the release.
A rollback is distinct from a roll-forward and from a hotfix. Rolling forward means shipping a new fix on top of the broken release rather than going back, which is faster when the fix is obvious and the rollback is expensive, and slower when it is not. A hotfix is a small roll-forward for one defect. Feature flags change the calculation: if the risky change is behind a flag, turning it off is the rollback, it takes seconds, and it leaves the deployment in place. A rollback plan states which of these applies to this release, because the answer differs by change.
Plans fail on data. A code rollback is usually mechanical; a database that has already accepted writes in a new shape is not, and the team discovers at midnight that the old version cannot read the rows the new one wrote. The prevention is expand-and-contract migrations, where the schema is changed additively first and the old code keeps working. The second failure is a plan that was never rehearsed: the restore command needs a credential nobody present has, or the previous artefact was pruned. A rollback that has been executed on staging is a plan; one that has only been written is a hope.
Common questions
What should a rollback plan include?
The trigger that justifies it, the person authorised to call it and a deputy, the exact version or artefact to restore and the command or mechanism that restores it, the handling of data written since the release, the smoke test that confirms the rollback worked, and who tells customers and support. Each item is checked on staging before the release, not read for the first time during the incident.
When should you roll back instead of fixing forward?
Roll back when the cause is unclear, the damage is ongoing and the previous version is known to work, because a rollback is a rehearsed step and a fix under pressure is not. Fix forward when the cause is obvious, the fix is small, and the rollback would lose data or take longer than the fix. The plan names the default for this release in advance.
Why are database changes hard to roll back?
Code is replaced; data accumulates. Once the new version has written rows in a new shape, restoring the old code leaves it facing columns it does not know or rows it cannot parse, and reversing the migration destroys what was written. Expand-and-contract migrations avoid this by adding the new shape first, keeping the old code working, and removing the old shape only after the release has held.
Who decides to roll back a release?
One named person with a named deputy, written into the plan before the release: the release manager, the on-call engineer leading the incident, or the product owner. The trigger is also written in advance, so that the decision is a comparison of a signal against a threshold rather than a debate. A rollback that needs a meeting to authorise it arrives after the damage has spread.
How do you test a rollback plan?
By executing it on staging as part of release readiness: deploy the release candidate, run the smoke test, then run the rollback exactly as written, with the same credentials, the same artefact store and the same person who would do it in production, and run the smoke test again against the restored version. The rehearsal finds the pruned artefact, the missing permission and the migration that does not reverse, while there is time to fix them.
Bug reports that arrive ready to triage.
Collect replay, console, network and browser context with the Free plan.