By Keith Rull ·
An architecture decision stays reversible when a named person can restore the previous behavior and account for what happened while the new path was on. Write the rollback, its owner, and its limits before the rollout. Sending traffic back is not a full rollback if the new path already accepted work you cannot restore.
That is the short rule. The rest is what to write down, and when to retire the old path.
What has to be true before you call it reversible?
Reversible means you can get the previous behavior back, on purpose, inside a window you have named. It also means you can explain the side effects that happened in between. A feature flag that flips routing is one piece. It is not the whole decision.
Ask three questions before you treat the change as safe to try.
What behavior do you need to restore? Name the user-visible outcome, not the component. “Reads come from the old store” is a behavior. “We revert the pull request” is a hope.
Who can make the call, and who can carry it out? The person who may pause the rollout and the person who may invoke rollback should be named, and they need access to the controls. If the only person who can roll back is asleep, or on a plane, the decision is reversible on paper.
What will the rollback fail to undo? Writes accepted by a new store, emails already sent, and records already deleted do not come back because you flipped a switch. Those need a separate reconciliation step, or they need to stay out of the first rollout. I use the same habit on risky changes that I describe for production access in general: write down who can touch the system, and rehearse the recovery while the change is still small. The case studies page walks a hypothetical write-path move in that spirit. This article uses a real release from this site.
What do you write in the decision record?
This portfolio builds five sites as separate static sites. A normal build writes the public output. An editorial build uses a separate output directory, so a reviewer can read draft material while the regular build leaves it out. A separate setting controls whether a build invites indexing. Those boundaries give a release reviewer a short list to check in the generated files.
The record below is for one brand release on this site. The checks match the repository’s build and the release runbook. You can reproduce the local checks with pnpm build and pnpm test:dist. I have not timed a full staging rehearsal of the recovery, so this record does not promise a number of minutes.
| Decision record field | What to write down |
|---|---|
| Change | Prepare a release of one brand while keeping its previous static build. |
| Evidence before promotion | Open a representative page, verify its canonical URL and robots settings, and confirm that an unapproved case-study route has no generated page and no sitemap entry. |
| Stop condition | Pause if an expected page is missing, a draft appears in the artifact, or the indexing policy differs from the generated metadata. |
| Rollback | Redeploy the last good commit, or sync that build’s artifact with the same cache headers and invalidate the cache. Because deploys do not delete objects, older hashed assets remain. Versioned objects can be restored one by one. |
| Limit | Restoring the previous build can remove content from the origin. Copies already fetched by people or crawlers may persist. A DNS change is a separate reviewed step, not part of this rollback. |
Read that limit row twice. Rollback restores a known build. It does not erase a page someone already cached, and it does not quietly undo a DNS change. If your change can accept new writes, add a row for how those writes get reconciled. The table above does not need that row, because a static release does not take customer writes.
For a change that does take writes, the record gets longer. Suppose, as a hypothetical, a team moves one preference field to a new store. The flag can send reads back to the old store in a second. The writes the new store accepted during the trial still have to be merged or discarded, and someone has to say which store was authoritative at each moment. Until that sentence is in the record, I would not call the migration reversible. I would call it a flag in front of a one-way door.
How do you know the old path can go?
Keep the previous build, and the assets it references, for the rollback window you agreed. Put a review date on the record, and write the evidence you will use to retire the old path. Evidence is a clean window: no stop condition tripped, the new path served the pages you listed, and the person who can roll back agrees the window can close.
Retiring the old path is itself a decision. Once you delete the last usable copy, or you end compatibility with the old system, update the record with the recovery options that still exist. “We can roll back” becomes “we can restore an object from versioning, and we cannot recreate the old path.” Say that while it is still true, not after someone asks during an incident.
A database cutover costs more to hold open, because someone has to reconcile data and answer failures on both paths. That cost is a reason to set a short review date. It is not a reason to skip the record. The date is how the temporary state ends on purpose.
What would I do before a risky rollout?
On this portfolio I would not promote a brand build until the evidence row in that table is true in the generated files. I would keep the previous artifact, name who may redeploy it, and leave the recovery time blank until a staging rehearsal measures it. Promising a window I have not practiced is how a reversible plan becomes a slogan.
I would also separate the changes that a rollback can undo from the changes it cannot. Indexing flags, canonical URLs, and which routes exist are reversible with a prior build. A DNS cutover is not part of that same switch. Customer writes, if this site ever took them, would need their own reconciliation row before I turned the new path on.
You can write this record without me when the change is small, the old artifact is already retained, and the person on call has used the rollback once on purpose. Bring in another set of eyes when the change accepts writes, when more than one team shares the decision, or when the only rollback anyone can describe is “we will revert the pull request.” Engagements that start from a single architecture call are described on work with Keith.
When the team that will own the release still has to practice the fallback, that is a delivery problem as well as an architecture one. Product development is how a first release gets a rollback procedure in the handoff, not in a later slide. When the decision is stuck between teams rather than inside one codebase, a Forward Deployed CTO sits in the reviews until that team can ship and recover it. A buyer who wants to know whether the architecture can be undone is doing technical due diligence, and this record is what they should ask to read.
FAQ
Who should be allowed to roll back?
Name a person who may pause the rollout, and a person who may run the rollback. They can be the same person only if a backup can run it too. Give them the access before the change, and have them run the recovery once while the blast radius is still a staging build. Authority that exists only in a slide is not authority.
Is a feature flag the same as a rollback?
A flag can restore routing. It restores behavior only when routing was the whole change. If the new path accepted writes, sent messages, or deleted data, the flag is the start of the rollback, and reconciliation is the rest. Write both in the record, or keep those side effects out of the first step.
What if part of the change cannot be undone?
Say so in the limit row, in plain words, before you ship. Then decide whether that part belongs in this rollout. A change with an irreversible step can still be worth making. It should not be described as reversible. Split the reversible step from the permanent one, and put a review on each.
When should we delete the old path?
After the review date, when the evidence you wrote down is actually true, and the owner of the rollback agrees. Deleting the old path early feels tidy. It also removes the option you just promised the business. Update the record on the day you delete it, so the next person knows which recovery options remain.
If you’re weighing a decision like this, talk to us.