Incident postmortems vs changelog: what to publish after things break

A bad day in production can produce up to three public documents, and teams constantly confuse them. The status page is written during the incident and answers “is it just me, and are they on it?” The changelog entry is written when the fix ships and answers “what changed?” The postmortem is written days later, once you actually understand what happened, and answers the hardest question: “why should I still trust you with my workload?”

Most guides treat the postmortem as an internal engineering ritual — five whys, blameless retro, action items in a doc nobody reopens. This one is about the public side: when an incident earns a published postmortem, what belongs in it, where it should live, and the follow-through loop that almost every team drops — which happens to run straight through your changelog.

Three documents, three clocks

Each document runs on a different clock, and the clock explains the content.

  • The status page runs on minutes. It exists while the incident is live. Its updates are terse, timestamped, and allowed to be wrong in retrospect (“investigating elevated error rates” is a fine thing to have said at 14:02 even if the real cause turned out to be DNS). Nobody holds a status update to the standard of a considered account — that is precisely what makes it fast to publish.
  • The changelog runs on the release. When the fix deploys, the changelog gets an entry — symptom-first, per the hotfix communication guide: what was broken, who was affected, what you shipped. This entry exists even for incidents too small to ever get a postmortem.
  • The postmortem runs on understanding. It ships days or a couple of weeks after resolution, because its value is accuracy, not speed. Publishing a “postmortem” six hours after recovery just tells readers you are guessing in a calmer font.

The rule that follows from the clocks: never hold one document hostage to another. Ship the fix entry when the fix ships, even though the postmortem isn’t ready. Post the final status update when service recovers, even though you don’t yet know why it broke. Each document should link to the others as they appear — the two-pass edit pattern from the hotfix guide applies here at document scale.

Does this incident owe a public postmortem?

Not every incident does. A reasonable test is impact × duration × data:

  • Broad, user-visible impact — a meaningful fraction of users saw errors, lost access, or got wrong results. A blip that monitoring caught before users did stays on the status page.
  • Long enough that people arranged their day around it — an hour of downtime generates support tickets; an afternoon generates internal escalations at your customers’ companies, and those people need a document to forward.
  • Anything touching data — loss, corruption, or exposure. Data incidents owe an account almost regardless of duration, and if the incident was a security breach, the rules change entirely: that document is a disclosure with its own obligations, closer to the security advisory than to an operational postmortem. Don’t publish the recipe; do publish the impact.

Two or more of those and silence becomes its own message. The failure mode isn’t writing too few postmortems — it’s recovering from a six-hour outage, closing the status incident with “this is now resolved,” and never speaking of it again. Enterprise customers notice: “do you publish postmortems?” is a standard line item in the vendor questionnaires the compliance guide describes, and an SLA credit conversation goes very differently when there is a published account to point at.

What a public postmortem is actually for

It has three readers, and only one of them was awake during the incident.

  • The affected customer deciding whether this was bad luck or negligence. They are reading for one thing: evidence that you understand the failure well enough that this class of incident is now less likely. Vague causes read as “we don’t know,” which reads as “it will happen again.”
  • The prospect doing diligence months later, sent there by a procurement checklist or a competitor’s sales team. For this reader a well-written postmortem is, counterintuitively, a sales asset: it proves you handle failure like adults. Companies with famously good incident writeups earn trust from outages that would cost a silent competitor customers.
  • Your own team, next year, when something similar wobbles and someone asks “didn’t this happen before?” The public document is the findable summary; the internal one keeps the gory detail.

Blameless is a writing rule, not just a meeting rule. In the published account, causes are systems and processes, never named or countable humans. Not because nobody made a mistake — someone probably did — but because “an engineer ran the wrong command” is a dead end (you will always employ humans) while “the tooling accepted a production target without confirmation” is a fixable defect with a verifiable fix. This is the one genre where the agentless passive that the tone guide bans is doing honest work: “the flag was applied to the wrong environment” names the system boundary, not a scapegoat. “Human error” as a root cause is banned for the same reason — it is where the analysis stopped, not what the analysis found.

Anatomy of one worth reading

Summary first, always — most readers take the first paragraph and leave, and that paragraph must carry the exact impact window and the precise scope. Then the detail, in this order:

## Postmortem: API errors and delayed webhooks — March 12

**Summary.** Between 13:41 and 16:05 UTC on March 12, API requests
returned 5xx errors at rates up to 40%, and webhook delivery was
delayed by up to 90 minutes. Dashboards and data at rest were not
affected. No data was lost or exposed.

**Timeline (UTC).**
- 13:41 — Deploy of the connection-pool change began
- 13:47 — Alerts fired on API error rate; incident opened
- 14:10 — Rollback initiated; error rate began falling
- 14:35 — API error rates back to baseline
- 16:05 — Webhook backlog fully drained; incident closed

**What happened.** A change to connection pooling held connections
open under retry load. Under normal traffic the pool drained; under
the retry storm triggered by the first errors, it exhausted —
the failure amplified itself.

**Contributing causes.** The staging environment does not reproduce
production connection volume; the rollout proceeded without a
canary stage; retry behavior in one client library defaulted to
aggressive immediate retries.

**What we are changing.**
- Canary stage for all deploys touching connection handling
  — shipped March 14 (see changelog)
- Load test with production-shaped retry traffic — due March 28
- Jittered backoff defaults in client libraries — due April 4

**What we are not changing.** We considered raising pool limits
and decided against it: the limit failed loudly and bounded the
blast radius. The defect was the amplification, not the ceiling.

Details that separate a real account from theater:

  • Exact impact window, ISO dates, explicit timezone — your readers’ own incident channels are full of timestamps they will try to line up with yours.
  • Precise scope, stated positively and negatively. “Dashboards and data at rest were not affected” answers the question every reader actually has. “A small subset of users” is the weasel phrase that makes everything else in the document suspect — if you know it was small, you know the number.
  • Contributing causes, plural. Real incidents are conjunctions — a trigger meeting an amplifier meeting a gap in detection. A single triumphant “root cause” usually means the analysis stopped at the first satisfying answer.
  • Dated commitments, not intentions. “We will improve our testing” is decoration. “Load test with production-shaped retry traffic — due March 28” is a promise a reader can check. Which is the point: promises you’d rather not be checkable don’t belong in the document.
  • A “what we are not changing” section. Nothing signals a genuine analysis like a considered rejection. It also pre-empts the obvious “why don’t you just…” replies.
  • An apology in proportion. One sentence, plain register: “We know teams plan their day around this API being up, and we’re sorry.” Groveling reads as performance; its absence reads as indifference.

The changelog closes the loop

Here is the part almost everyone drops. A postmortem’s remediation list is a set of public promises — and the changelog is the natural place those promises become verifiable, because the remediations are shipped changes like any other.

  • The hotfix entry ships first, at fix time, and gains a link to the postmortem when it publishes (edit the entry — same URL, per the two-pass pattern).
  • Each remediation that ships gets an ordinary changelog entry with one extra line: “Part of the follow-up we committed to in the March 12 postmortem” — linked. Canary stage shipped? Entry. Backoff defaults changed in the client library? Entry (that one’s a behavior change users need anyway).
  • When the list is done, one closing line in the postmortem itself: “All follow-up items shipped — see the changelog.”

This costs three short entries and buys the thing postmortems are supposed to buy: demonstrated follow-through. A reader who lands on the postmortem a year later and can click through to the shipped fixes has watched you keep a promise in public. It is also the honest pressure your future self needs — a due date published next to a changelog people read is much harder to quietly miss than an action item in a retro doc.

Where each document lives

  • The postmortem attaches to the status page incident — that’s where affected users already looked, and where status-page subscribers get notified. But beware permalink rot: some status providers paginate old incidents into oblivion or expire them with the subscription. If the incident was serious enough for procurement to ask about in two years, keep a copy on a page you control.
  • The changelog stays product-changes-only. The incident narrative does not get pasted into the changelog — that’s the merge anti-pattern from the status page guide. The changelog carries the fix entry and the remediation entries, each linking out.
  • The blog is for the rare industry-lesson writeup — the incident so instructive that strangers who’ll never buy your product will read it. Those exist, they earn real respect, and they are maybe one in fifty incidents.
  • Email goes to contractually affected customers — SLA-covered accounts, per the enterprise guide’s advance- notice logic in reverse: the people owed credits should hear from you before they ask.

One more boundary: planned maintenance that went fine does not get a postmortem. Planned maintenance that blew its window is an incident, and the postmortem should say so plainly — “the migration exceeded its window” is a cause like any other.

Anti-patterns

  • The postmortem pasted into the changelog. Two thousand words of timeline between “New: CSV export” and “Fixed: dark-mode contrast.” Wrong document, wrong readers; link it instead.
  • “Root cause: human error.” The analysis stopped where it should have started. What allowed the error to reach production, propagate, and evade detection?
  • The unmarked promise graveyard. Remediation lists with no dates, or dates that pass silently. One tracked-and-shipped fix is worth five aspirations.
  • Weasel scope. “Some users may have experienced…” — you have metrics; they have tickets. Vague scope in the summary poisons trust in every precise claim below it.
  • The vanishing postmortem. Published on a status provider’s incident page that 404s after the platform migration. Postmortems are trust infrastructure; give them a permanent home.
  • The lawyer-scrubbed non-account. “A configuration issue with an upstream provider briefly impacted some services.” If legal review removed every fact, publishing the residue is worse than silence — it announces that a fuller story exists and you chose not to tell it.

Where Wakelog fits

Honestly: Wakelog is the changelog side of this triangle, not a status page and not an incident-management tool — pair it with whichever status provider you already use. What it does carry is the follow-through loop: the hotfix entry posted from the terminal while the incident channel is still scrolling, edited later to link the postmortem at the same permalink; remediation entries tagged fix or announcement so “what we changed after the incident” is a filterable, feedable list; and stable per-entry URLs that keep the “promised → shipped” chain clickable years later, including from the postmortem itself.

Create a free changelog — or start with the hotfix communication guide, which covers the first document you’ll write on a bad day.

Related guides

Last updated 2026-08-01 · All guides