Key takeaways
- State the single change and the systems it can affect before writing any procedure.
- Give the reviewer a stop condition that is observable, not a feeling that something looks wrong.
- Name who can approve the next step during the window, including a backup for each role.
- Attach the rollback command, the last known good state, and the person who verified both.
- Close the note with the observed result, any deviation, and the follow-up owner.
What the note has to decide
A maintenance-window note is a decision record for one bounded change. It tells the reviewer what will move, when it will move, and how the team will know whether the move worked. The note should fit on a page so an on-call engineer can read it while the window is open. If the change needs a longer document, split the change rather than the attention of the reader.
Write the note before the window opens and freeze it at the start of the window. Late edits during a live change make it impossible to tell whether the team followed the approved plan. If a real condition forces a change, record the deviation and the approver in the note itself. The next reviewer will then see what was planned and what actually happened, including the reason for the difference.
State the change and its blast radius
Name the service, the environment, and the exact artifact that will change. A version tag, a commit hash, or a migration number is more useful than a general description such as a database update. The reviewer needs enough detail to find the same artifact without asking which build was meant. Add the artifact location and the person who published it so the trail does not depend on memory.
Describe what can break and who would notice first. Include the upstream callers, the downstream stores, and any scheduled job that reads the affected data. A change that looks local can still break a report, an export, or a nightly reconciliation that nobody mentioned in the ticket. List those consumers by name and mark the ones the team has not tested.
List the verification and stop conditions
Write the checks in the order the team will run them. Start with the cheapest signal, such as a health endpoint or a row count, then move to a user-facing path. Each check needs an expected result and a place to record the observed value. A check without a recorded result is only a ceremony, and the next reviewer cannot tell whether it passed.
Add a stop condition for each risky step. A stop condition is an observable threshold, such as an error rate above the baseline or a queue depth that keeps climbing for ten minutes. The team should agree in advance who calls the stop and what happens next. Without that agreement, the person closest to the console makes the decision under pressure and with incomplete context.
Name the people and the decision path
List the change owner, the reviewer, and the person who can approve an exception. Add a backup for each role because a single name creates a queue when that person is unavailable. For an offshore pod, include the buyer-side approver and the overlap window when both sides can talk. Put the contact method beside each name rather than assuming the team uses the same channel.
Describe how a decision travels during the window. A shared channel with a named thread is usually enough, provided someone is assigned to watch it. Write down the escalation path if the change owner and the reviewer disagree. The path should end at a person who can accept the business risk, not at a group inbox that nobody owns in writing.
Record the rollback evidence
The rollback section should contain the command or procedure, the last known good state, and the expected recovery time. Include the data condition that makes a rollback unsafe, such as writes that cannot be reversed. A rollback plan that ignores new writes can turn a small failure into a larger recovery project. State the point after which the team must stop and recover forward instead.
Ask the person who will execute the rollback to read the section before the window starts. That reader should confirm the access, the artifact, and the dashboard are all available. A rollback that has never been opened by its operator is a hope, not a control. Record the confirmation in the note with a time and a name before the window.
Close the window with a review
Record the actual start and end time, the checks that passed, and any step that differed from the plan. Add the observed user impact and the state of the monitoring after the window. The record should let a reader who was asleep reconstruct the change in a few minutes. Include the final artifact version so the state is unambiguous in the record.
Assign one follow-up for each deviation and give it an owner and a date. A deviation that produces no follow-up will usually appear again in the next window. Review the note at the next delivery meeting and keep the completed record beside the release history. The pattern across several notes is more useful than any single review. A short review with the next on-call engineer is often enough to catch the pattern before it repeats.
Questions about assessing Philippine developers
Who should write the maintenance-window note?
The engineer who will run the change writes the first draft, and the reviewer who can approve an exception signs it. The buyer-side approver only needs to sign the risk section when the change crosses an agreed boundary.
How long should the note be?
One page is enough for a routine window. If the change cannot be described in a page, split it into smaller changes or attach a separate technical runbook and keep the note as the decision record.
What belongs in the deviation log?
Record the step that changed, the reason, the person who approved it, and the observed result. A deviation without an approver is an unplanned change, even when the outcome is good.
