The One-Page Change Record You Can Write in Five Minutes

Thursday, 17:40, at Bellweather Logistics. Jonas is about to switch the VPN gateway from its own list of users to the directory group. The aim is for the drivers' tablets at the four depots to log in with normal accounts. Fiona, coat on, asks over the partition: "What's the rollback?" Jonas says, "Switch it back." Fiona says, "To what?" Jonas opens the console to check the name of the old setting and finds that it is not a group. It is a local user list with sixty-one entries, and the switch he was about to make would delete it. He closes the console and goes home. The change happens the following Tuesday at 13:00, with the sixty-one users exported first, and nobody at any depot notices anything.

Fiona's question took eleven seconds. A change record is one page that asks it for her, along with six others. The questions cover what you are going to change, why, when, what could go wrong, how you will put it back, how you will know it worked, and who is involved. This article is part of our Lightweight Change Management series. It is about the record itself: the seven fields, what each one is for, and how to write the page in five minutes without it turning into a form.

It covers the seven fields and why each exists. Next come what, as one sentence a stranger can read; why, as a ticket number or a plain reason. Then come when, as a time rather than a mood; risk and rollback, the two fields people skip. Next are test, how you will know it worked; who, as three names. Then come writing it in five minutes, with a worked example; closing the record afterwards. Finally come a short war story and the template to copy, in that order.

Seven Fields and Why Each Exists

The record has seven fields: what, why, when, risk, rollback, test and who. Each exists because skipping it has a known cost. What, so the change can be found. Why, so it can be judged. When, so it can be scheduled around. Risk, so it can be reviewed. Rollback, so it can be undone. Test, so you know when it is finished. Who, so someone can be asked. Seven is the number. A record with twelve fields is a form, and a form gets filled in with "N/A".

The seven split between the two jobs that change management does. What, when and who serve "knowing what changed": they are the fields a colleague reads six months later with an outage in front of them. Why, risk, rollback and test serve "not breaking things": they are the fields a reviewer reads the day before. A record with only the first three is a log entry, which is all a standard change needs. The full seven is a plan, and a normal or emergency change gets the plan. Which changes are which is settled in What Needs Review and What Does Not.

What: One Sentence a Stranger Can Read

The what field names the system, the setting, the value before and the value after, in one sentence. "Firewall: add rule allowing TCP 443 from the depot subnet to srv-booking; currently blocked." Not "firewall change for booking". The test is whether a colleague who was not there, reading it in six months with the console open, can point at the exact thing. If they would have to ask, the sentence is not finished.

The before value matters more than people expect. The after value is the change, and everyone remembers to write it. The before value is the raw material of the rollback and, in most environments, the only record that the old value ever existed. "Timeout: before 30 seconds, after 10 seconds" is nine words. On the day the new value turns out to be wrong, those nine words are the difference between a two-minute revert and an afternoon of guessing.

Why: The Ticket Number or the Reason

Why is one line: the incident it fixes, the problem record it closes, the request it fulfils, or a plain reason in words. "Fixes 6630: drivers cannot use normal passwords on tablets." "Supplier advised in their reference 4471." "Because the old rule has not matched in eleven months." A reason does not have to be grand, and "because it was annoying" is a legitimate entry. What it cannot be is blank, because the reviewer uses the why to judge whether the change is worth its risk. The log reader uses it six months later to decide whether the change can safely be undone.

A change with no why becomes the rule nobody dares remove. Every network has one: the firewall entry, the scheduled task, the group with an odd name, that nobody will touch because nobody knows what depends on it. Each of them once had a reason. The reason went home with the person who had it. One line on the record, written on the day, is the whole cost of never having that rule.

When: A Time, Not a Mood

When is a date, a start time, an expected duration, and who is affected during it. "Tuesday at 13:00, about twenty minutes, booking site unavailable throughout." Not "this week", not "when it goes quiet", and not "tonight" unless tonight has a time on it. The review uses the when to find conflicts: two changes on one system, a change during the payroll run, a change whose only rollback expert is on leave. The calendar that does the finding is described in A Change Review That Takes Fifteen Minutes. The record's job is to give it something to put on the calendar.

Pick the time by who is affected, not by when you happen to be free. Friday at 17:30 is when you are free. It is also when nobody is around to notice a breakage until Monday at 08:00, when the drivers notice it for you. Mid-morning midweek is the honest default for anything whose rollback takes more than a few minutes. People are in, the supplier's support line is open, and a failed change gets found while the person who made it is still at their desk. Things break on their own schedule. There is no need to give them a weekend's head start.

Risk and Rollback: The Two Fields People Skip

Risk is one line that answers two questions: who notices if it goes wrong, and how? "Depot drivers cannot log in to tablets; they would phone the desk; four depots, about ninety drivers." Not a score, not a colour, not a matrix. The five questions a reviewer asks are in the classification article. The risk line on the record is the answer to the first of them, written down so the reviewer can start from it rather than guess at it. A risk line that reads "low" has not answered either question.

Rollback is the exact steps to put the system back to its before state, and how long they take. It also says whether something must be saved before the change for the rollback to be possible. "Rollback: re-import users.csv, exported at step one, via the gateway's local-users import; about five minutes." Not "switch it back". Not "reinstall", which is not a rollback but a hope with a longer runtime. And not "restore from backup" unless the line also says when that backup was last verified and how long the restore takes. A rollback nobody has timed is a rollback nobody has.

The rollback field is where a record finds its own mistake, which is why it is written second. Writing "switch it back" forces the question "to what?" Answering it means looking at the before state, and the before state is where the surprises live. That is how Jonas found sixty-one local users he did not know existed, on Thursday evening, with the console open and nothing yet changed. The field did not prevent an outage by being read. It prevented one by being written.

Some changes have no rollback, and the honest record says so. A firmware update with no downgrade path, a data migration whose output is already in use, a certificate whose predecessor has expired. Write "No rollback: forward fix only. Full backup taken at step one; a restore takes about four hours." The review treats a change with no rollback as a higher-risk change and asks for a quieter window and a second person. "None, honestly" is a better entry than "switch it back", and the reviewer can work with it.

Test: How You Will Know It Worked

Test is the check you will do immediately after, the check you will do the next morning, and the name of the person who confirms. "Test: log in from a depot tablet with a driver account; confirm the gateway log shows the group name; ask Priya at the Northside depot to confirm by 09:00 Wednesday." It is written before the change, not after, because afterwards the temptation is to declare success at the first green light and go home.

Two tests, not one. The immediate test proves the change does what it was meant to do. The delayed test, next morning, proves it did not break something else overnight. That is the failure the immediate test cannot see: the scheduled job that runs at 02:00, the branch office that only connects at 08:30, the certificate that five other things used. The delayed test has a time and a name on it, and the name is usually someone outside the desk who would notice first.

If the change fulfils a request, the requester is part of the test. "Done" for a request is not when the setting is changed; it is when the person who asked confirms that what they asked for now works. Write the requester's name on the test line and the time by which you will ask them. The change is not closed until they answer or the time passes with silence.

Who: Three Names

Who is three names. The doer: one person, even when two are in the room, so that there is someone to ask. The second person: whoever read the record at the review and, for a change with two or more high risk answers, whoever is present when it is made. And the informed: the people told before and after, which is a list rather than a name. The depot managers. The desk, so it knows what the next hour's tickets mean. The requester, so they know when to look.

The informed line is the one that stops the twenty-two tickets. The people who will notice are told in advance, in one sentence with a time in it: "The booking site will be unavailable on Tuesday between 13:00 and 13:20 while we move it to the new server." The sentence is drafted on the record, so that it gets sent, and it is sent the day before, so that it gets read. Nobody has ever raised a ticket about an outage they were warned of in writing the day before. People raise tickets about surprises.

Writing It in Five Minutes

Write the fields in this order: what, rollback, test, when, why, risk, who. What first, because it is the thing, and writing it with the before and after values means you have the console open. Rollback second, while the console is still open, because that is where the surprises are, and it is cheaper to find them with nothing changed. Test third, because it tells you what "finished" means. The other four are one line each and take a minute between them. Five minutes is honest for a change you understand.

If the record takes twenty minutes, the record is not slow; the change is less understood than it seemed. The twenty minutes were going to be spent either way. The record moved them from after the outage to before the change, which is the cheapest place minutes can be spent. I have abandoned changes on line five of the record, and every one of them deserved it.

Here is Jonas's record for the Tuesday, as he wrote it on the Friday morning, in five minutes and a bit. It is the template with the blanks filled in, and it is the kind of record the weekly review reads in ninety seconds.

CHANGE RECORD — CHG 6641
What:     VPN gateway: switch authentication from the local user list
          (61 users) to directory group "Drivers-VPN".
          Before: local list.  After: directory group.
Why:      Fixes 6630: drivers cannot use their normal passwords on
          depot tablets; local list has no password expiry.
When:     Tuesday at 13:00, about 20 minutes. Tablets cannot connect
          during the switch; depots told the day before.
Risk:     Drivers at four depots (about 90) cannot log in if the
          group mapping is wrong; they would phone the desk.
Rollback: Step one exports the local list to users.csv. If the group
          fails, re-import users.csv via the gateway's local-users
          import and set authentication back to local; 5 minutes.
Test:     Immediate: log in from a depot tablet with a driver account;
          gateway log shows "Drivers-VPN". Next morning: Priya at
          Northside confirms by 09:00 Wednesday that drivers are in.
Who:      Doer: Jonas.  Second: Fiona (read at review, present at 13:00).
          Informed: depot managers (Monday), desk, Priya.
Kind:     Normal.   Reviewed: Thursday review.   Outcome: ________

Where the record lives depends on the tool and the convention in Tracking Changes Without a Change Module. But the short answer is: in a ticket, as the first note, with the kind on the subject line. Keep the blank template open on the second screen all week. For a repeat of a normal change made before, copy the last record and edit the values; the five minutes become two, and the rollback is already known to work.

Resist adding fields. Every change process that ever drowned a team started with seven fields and gained one a quarter: business justification, financial impact, configuration item, category, sub-category, approver signature, risk score. Each is sensible somewhere. Each costs a minute. At twelve the record is a form, the form is filled with "N/A" and "see above", and the review stops reading it. If an auditor needs a field, add it to the records the auditor will read, and leave the rest at seven.

Closing the Record After the Change

When the change is made, add the outcome line: done, rolled back, or partial; the actual start and end times; and anything unexpected. "Done 13:04 to 13:19. Unexpected: two drivers had old credentials cached and needed to sign out and in; no other effects." The outcome line is what turns the record from a plan into history. It is what the next person reads, on the morning the gateway misbehaves, to decide whether CHG 6641 is a suspect or an alibi.

A record without an outcome is ambiguous forever. Did it happen? Did it work? Was it the Tuesday or the Thursday? The weekly review spends its first two minutes reading last week's outcome lines. A record with a blank where the outcome should be is asked about by name. Write the outcome the same day, while the times are still in your head, and write the unexpected part honestly. "Nothing unexpected" is a fine outcome and the most common one. "Rolled back at 13:11, see note" is a fine outcome too, and the note that follows it is the most useful sentence on the whole page. How to write a note that someone can use later is a subject of its own, in Resolution Notes Worth Reading Later. The same rules apply here.

A Short War Story: The Eleven-Hour Rollback at Stonebridge Insurance

Hugo patched the database server behind Stonebridge Insurance's policy-administration system on a Wednesday evening, with a change record whose rollback line read, in full, "restore from backup". The patch left the database service unable to start. At 22:10 he began the restore, which is when he learned two things. The last good backup was from the previous Friday, because the nightly job had been failing silently for four days. And a full restore on that hardware took eleven hours. Forty claims handlers worked from paper on Thursday, and three days of policy changes were re-keyed over the weekend by people who had not planned to be there. The cost was roughly two hundred staff hours and a letter to the regulator explaining the gap. A rollback line written honestly would have said "restore from backup, last verified on ____, takes ____ hours". The two blanks would have sent Hugo to check the backup before the patch, where four days of failures were waiting to be found. The lesson Stonebridge took was that the rollback field is not a formality but the one place the record asks you to look before you leap.

The Change Record Template

The template below is the seven fields on one page, with the kind, the review and the outcome at the bottom. Paste it into the first note of a change ticket, or into whatever your desk uses as the record. Fill it in the writing order: what, rollback, test, then the rest. Keep the headings exactly as they are. That way, every record on the desk reads the same way and the review can find the rollback line without hunting for it.

CHANGE RECORD — ONE PAGE
Change number: ________   Kind: [ ] standard  [ ] normal  [ ] emergency

WHAT      System: ______________________  Setting or component: ______________
          Before: ____________________________________________________
          After:  ____________________________________________________

WHY       Fixes / fulfils / closes: ticket ________   or reason:
          ____________________________________________________________

WHEN      Date: ________  Start: ____:____  Expected duration: ____ min
          Affected during the change: ___________________________________
          Told in advance by: ________  on: ________

RISK      Who notices if it goes wrong, and how:
          ____________________________________________________________
          High answers to the five questions: ____ of 5

ROLLBACK  Must be saved or exported first: __________________________
          Steps to put it back: ________________________________________
          ____________________________________________________________
          Takes about: ____ min    Last known to work on: ________
          [ ] No rollback: forward fix only; backup taken; restore takes ____ h

TEST      Immediately after: ___________________________________________
          Next morning, by ____:____: ___________________________________
          Confirmed by (name): __________________

WHO       Doer: ____________   Second person: ____________
          Informed before: ______________________________________
          Informed after:  ______________________________________

REVIEW    Read at the review on: ________   Questions raised: ____________

OUTCOME   [ ] done  [ ] rolled back  [ ] partial    Actual: ____:____ to ____:____
          Unexpected: ___________________________________________________
          Follow-up ticket, if any: ________

Jonas's change went in on the Tuesday at 13:04, with the sixty-one users exported first. Priya at Northside confirmed at 08:40 on the Wednesday that every driver was in. The record took him six minutes, one over, and he has written about forty since. The only one that took twenty minutes was for a change that should not have been made at all. The record told him so on the rollback line, which is exactly where it is supposed to.

Frequently Asked Questions