The rollback used to be the last part of my change notes. I’d describe what I wanted to alter, list the commands, think through validation, and then add a reassuring line about putting things back if necessary.
That order made emotional sense. The change was the interesting part. Rollback was paperwork for a future I didn’t expect to visit. It also meant I was designing the exit after I’d already become attached to the entrance.
Now I write the rollback first.
This starts with a plain description of the current state. Which file or image is active? Where does the existing data live? Which service definition is actually being used? What must remain untouched for the old path to work again? If I can’t answer those questions before changing anything, I’m not ready to improve the system. I’m still discovering it.
The exercise often catches an uncomfortable detail early. Maybe the previous package is no longer available. Maybe a migration changes data in place. Maybe the configuration I planned to save isn’t the only configuration involved. Maybe “switch back” depends on a network route or credential I haven’t tested in a while. None of those discoveries makes the change impossible. They change the kind of change I’m about to make.
There’s a difference between a reversible edit and a one-way migration with a recovery plan. I used to blur those together because both could fit under a heading called rollback. Writing the steps before the change makes the distinction harder to ignore. If returning requires restoring data, rebuilding an image, and reconciling writes made after the cutover, that isn’t a quick rollback. It’s another operation, and it deserves that name.
The first draft of a rollback is usually too vague. “Restore the old configuration” leaves me asking which copy, from where, and how I’ll know it loaded. “Redeploy the previous version” assumes the artifact still exists and the deployment tool can select it without regenerating something nearby. “Revert the database” is the sort of sentence that looks calm only because it has declined to include any mechanics.
So I make the wording executable. Stop the writer. Preserve the new state if it may be needed for diagnosis. Put the previous file back at the path the service reads. Start the known image. Confirm that the process loaded the expected configuration. Exercise the old path. The exact sequence changes with the system, but every verb needs an object I can identify before the work begins.
That last check matters. A rollback isn’t complete when the reverse commands exit cleanly. The former behavior has to be usable again. If I can’t state what I’ll observe after returning, I have a reversal procedure without a recovery condition.
Writing this early also changes the forward plan. I stop treating the old path as debris to remove during the exciting part. I preserve the current image, keep the configuration copy readable, and avoid combining cleanup with cutover. If a data transformation can’t be reversed, I may choose a side-by-side destination or an export before it runs. The rollback stops being a paragraph and begins shaping the architecture of the change.
That influence is exactly why it belongs first. An exit designed after the implementation can only work with whatever options the implementation happened to leave behind.
I’ve noticed another effect: the plan becomes less optimistic without becoming more fearful. Once I know how to return, I can make the forward steps smaller. I can name a point after which rollback becomes restoration. I can decide which observations justify continuing and which ones send me back. I don’t have to improvise those thresholds while a changed system is already demanding attention.
Sometimes the exercise tells me not to proceed. If the current state can’t be reconstructed, the old artifact is gone, or the data boundary is poorly understood, I pause and fix that first. That can feel like losing momentum. In practice, the momentum was imaginary. I was preparing to move quickly into a state I couldn’t leave.
The note is also for the version of me who will be more hurried later. During a change, small surprises consume working memory. A command returns a warning. A dependent service takes longer to settle. A screen looks slightly wrong. That’s a bad moment to ask my brain to recreate the old topology from first principles. The written rollback gives me a path that was designed while the system was still quiet.
I don’t pretend the document makes reversal automatic. Conditions can change after the plan is written. New data may arrive. A dependency can fail independently. The safe action may be to stop and investigate rather than force either direction. A rollback plan is not a promise that backward is always available.
It is a test of whether backward is available now, before I spend it.
My change notes still contain the forward steps, validation, and cleanup. They’re simply built around a different first question. Before I write what I’m about to make true, I write how I would make the present state true again. More than once, the most important result has been crossing out the word “rollback” and writing “restore.” That correction is much cheaper before the first command runs.