The maintenance window: communicate the downtime you chose

Planned downtime is the only outage you get to schedule, and it is the only one customers forgive — if you tell them the truth about it. The failure mode is never the 40 minutes of read-only mode; it is the surprise: the app that will not save at 2 a.m., the support inbox full of “is this broken?”, the error budget silently drained by downtime you did not announce. A maintenance window done right is a promise with five facts, five announcement beats, and a cap rule that keeps an overrun from becoming a silent one. The database outage runbook covers the window that goes sideways anyway; this page covers the part you control before it starts.

One distinction first: a maintenance window is downtime by appointment, and communicated windows do not spend the error budget. That is the deal — but the deal only holds if the communication is real. A window nobody heard about is just an outage you caused on purpose, which is worse, because you signed the change ticket.

1. One line, five facts

Every announcement — first notice, reminder, or completion — carries the same five facts on one line. If a reader can quote all five back to you, the announcement worked:

• What: “order history and saved carts will be read-only” — the user-visible surface, not the internal ticket (“PG 14→15 major version migration” is for the changelog, not the customer).
• When: date + clock time with the timezone named: “Sunday 14 Sep, 02:00–04:00 ACST”. “2 a.m.” is a timezone you assumed; a global customer base will not guess which one.
• Duration cap: the window is a cap, not an estimate. You are promising to be done by 04:00, not around then. The cap is what makes the extension rule (below) enforceable.
• What to expect: read-only? Offline? Working but slow, with writes queued? One sentence, plain language, no internal topology.
• Where updates land: the status page URL and the one channel you will actually update. “Follow us for updates” is not a place; it is a shrug.

2. Five beats, one skeleton

The window has five communication beats. Each is two or three sentences, and each reuses the five-facts line so nobody has to remember an earlier email:

• T−7 days — first notice. The five facts plus one line of why: “We're moving order history to a faster database. To do it safely, it'll be read-only for up to two hours.” Email + in-app banner + status page scheduled entry. Anything that touches money or identity gets T−14 instead.
• T−24 hours — reminder. Same line, unchanged. Do not improve the wording between beats — a changed fact reads as a changed plan, and someone will quote the old one back at you.
• T−1 hour — starting soon. “Window starts in one hour (02:00 ACST). Next update when it's done, or at the 04:00 cap, whichever comes first.” That last clause is doing real work: it names the next-update clock so silence has a deadline.
• During — start, done, or extended. At 02:00: “Started on time.” When finished: “Done at 03:41 — 19 minutes under the cap. Writes are live; if anything looks wrong, reply here.” Only if the cap arrives first: the extension message (below).
• After — completed note. Same five facts plus what changed: “Completed at 03:41 ACST, 19 minutes under the two-hour cap. Order history is on the new database — faster search, same URLs. No action needed from you.”

Five beats is not over-communication. The alternative is a customer who set an alarm to finish a report at 03:00 discovering a read-only app with no answer in the inbox — and drafting the cancellation email while they wait.

3. The cap rule: extensions are announced, overruns are not

The duration cap exists for one rule: you may run over, you may never run over silently. The mechanics:

• Done early? Announce it. “Done at 03:41, 19 minutes under cap” builds the credibility you will spend the day a real outage happens.
• Cap reached, work incomplete? At the cap minute — not fifteen after — send the extension: “02:00–04:00 window has hit its 04:00 cap. Migration is 80% done and data is safe; we're extending to 04:30 (new cap). Next update at 04:30 at the latest.” A named new cap converts an overrun into a plan.
• Second cap reached? Abort. Roll back to the pre-window state, announce “we're stopping and rescheduling” with the reason and the make-good date, and post-mortem the estimate in daylight. A third extension is not persistence; it is a team that cannot read its own progress, operating on a system that customers are actively using.

The one unforgivable version is the silent overrun: work quietly until 05:20, announce “done!” — and never mention that for 80 minutes every status page and every promise was a lie. Customers forgive announced extensions. They churn on silent ones, because the silent overrun tells them what you will do during a real incident.

4. What belongs in a window — and what never does

A window is expensive: it costs announcement effort, customer attention, and an on-call Sunday. Spend it on work that needs it:

• Belongs: major version migrations; failover and PITR-restore drills; storage re-shards; anything whose rollback is measured in hours, not seconds. If the restore path is the safety net, do it in a window.
• Never belongs: routine deploys that roll back in seconds; config flips behind a flag; anything you could ship Tuesday afternoon without anyone noticing. If the change can be made invisible with a canary, making customers sit through a window for it is malpractice dressed as caution.
• The test: if the change fails, is the rollback faster than the next window? Fast rollback → normal deploy. Slow rollback → window. That is the whole decision.

5. Abort criteria, written before the window

Every window opens with abort criteria written down before it starts, and a named person who owns the abort call:

• Time trigger: “if the migration has not reached step 4 by 03:15, abort and roll back” — not “if things feel slow.” Feelings negotiate; a clock time does not.
• Verification trigger: the post-change verification query (row counts, checksum sample, a real order through a test cart) defines done. If it fails twice, that is an abort, not a third attempt.
• Named authority: one person on the call can say “abort” and everyone executes. If the person who wants the migration to succeed is the only one allowed to stop it, you do not have an abort rule — you have a gambler.

Write the rollback entry point next to it: which command, which snapshot, how long it takes. The database runbook's state-capture step applies here too — if the window aborts, the capture becomes the post-mortem's best evidence.

6. Worked example

A twelve-person SaaS schedules its order-database major-version migration for Sunday 02:00–04:00 ACST. T−7 email has the five facts; T−24 reminder is unchanged; T−1h names the next-update clock. The window starts on time. At 04:00 the migration is at 80% — the extension goes out at 04:00 exactly, new cap 04:30, reason named. Done at 04:23; the completed note reports the extension, the reason, and one sentence of what changed. Zero confused support tickets, two replies that said “thanks for the updates,” and the error budget untouched — the window was communicated, so it was downtime by appointment, not spend.

The counter-example: the same team, six months earlier, had scheduled a “quick 30-minute” window that ran 90 minutes over with no updates. Forty support tickets, one churned account that cited “we couldn't tell what was happening,” and a retrospective that produced this exact template. The engineering work in both cases was similar; the difference was entirely in the promises kept.

7. Metrics

• Announcement lead time ≥72 hours for every window (money-touching: ≥7 days).
• Extension announcements: 100% — every cap arrival produces a message, every time.
• Silent overruns: zero. This metric is binary and it is the reputation metric.
• Windows finishing under cap: ≥90% — chronic overruns mean the estimates (or the scope) need fixing, not the comms.

From the HIVE80lab kit

• The First 30 Minutes — free incident quick-start
• Ops Starter Kit — incident response for small teams — $14
• Ops Starter Kit Vol. 2 — advanced incident response & communications — $27
• Ops Mega Bundle — all 5 kits in one download — $29

Related: the change freeze window policy covers the dates when no changes go out at all, the error budget policy explains why a communicated window is the one kind of downtime that doesn't spend the budget, and the database outage runbook is for when the carefully announced window turns into the real thing.

Flag removals are window work when the rollback is slow: the feature flag cleanup checklist decides which flags survive, and the maintenance window policy decides when they are deleted.