Hotfix communication: announcing emergency fixes without spreading panic

A hotfix is a release you didn't plan: something broke badly enough that the fix can't wait for the next train. The code side of a hotfix is well understood — branch, cherry-pick, ship. The communication side is where teams actually lose trust, because a hotfix is the one release your users may already be experiencing before you say a word. This guide covers what to publish, when, and where — while the fix is still rolling out and after it lands.

The reader is stressed. Answer four questions, in order

Nobody reads a hotfix announcement out of curiosity. They read it because something is broken for them right now, or because they fear it might be. In that state a reader wants exactly four answers, in this order:

  1. Am I affected? Which versions, platforms, plans, or regions. Be concrete: "self-hosted 2.4.0–2.4.2" beats "some users".
  2. What does it look like? The symptom, in the user's words — "exports hang at 99%", "you may have been signed out repeatedly". This is how a reader matches the announcement to their experience.
  3. Is it fixed, and how do I get the fix? Auto-deployed? Update manually? Which version number carries it?
  4. Do I need to do anything else? Re-run a job, rotate a key, re-save a setting — or, explicitly, nothing. "No action needed" is information; silence is not.

Root cause, timeline, and lessons learned are question five through seven — they matter, but they can come later. Don't hold the announcement hostage to the post-mortem.

Publish in two passes: fast stub, full entry

Hotfix communication has a speed–completeness tension: the full story isn't known while users are hurting. The answer is to publish twice, in the same place:

  • Pass one — at ship time. Symptom, affected scope, fix version, required action. Four sentences is enough. Publish the moment the fix is actually reaching users — not when it's merged (see announce when usable; it applies double under pressure, because "fixed!" followed by the bug still happening burns more trust than the bug did).
  • Pass two — within a day or two. Edit the same entry, or append a short follow-up: what caused it, what you changed so it doesn't recur, and a link to a full post-mortem if you write one. Keep the URL stable — people share hotfix links in support threads, and a moved link during an incident is a small extra failure.

Title with the symptom, not the fix

An affected user scans your changelog looking for their problem. Titles that work name the user-visible symptom:

  • Good: "Fixed: exports stuck at 99% for large workspaces (2.4.3)"
  • Good: "Hotfix: repeated sign-outs on mobile — resolved in today's update"
  • Bad: "2.4.3" — says nothing; the reader with a broken export scrolls past it.
  • Bad: "Fix race condition in SessionRefreshWorker" — the cause, in your vocabulary. The symptom-first rule is never more important than during an incident.

Security hotfixes: precise about impact, vague about the recipe

A security fix inverts one rule. For an ordinary bug, more detail is better everywhere. For a vulnerability, be precise about impact and action — who's exposed, what an attacker could do in principle, what to update to, whether to rotate credentials — and vague about the recipe until users have had time to update. "We've fixed a vulnerability" with no impact statement reads as a cover-up (the security template covers the wording); a working exploit walkthrough on ship day arms attackers against everyone who hasn't updated yet. Publish the identifier (CVE if you have one), credit the reporter if they wish, and save the technical deep-dive for a dated follow-up.

Where it goes: status page during, changelog after

If you run a status page, the division of labor from the status-page guide holds under pressure: the status page carries the incident while it's open ("we know, we're on it, workaround here"), and the changelog carries the durable record — the hotfix entry — once something actually shipped. Close the loop by linking both ways: the incident's resolution note links to the hotfix entry; the entry links to the incident timeline. If you have chat channels wired up (webhook, not bot), a hotfix is one of the few posts that justifies a ping — it's exactly what subscribers stayed subscribed for. And if the broken thing was recently announced as a feature, drop a short update on that announcement too; its readers are the affected population.

Never fix it silently

The strongest temptation with an embarrassing bug is to ship the fix and say nothing. Resist it. Users who hit the bug noticed; support threads about it stay open forever; and anyone who later diffs your versions (auto-update readers, package-bump reviewers, dataminers — see the stealth-nerf rule) will find the change and ask why you hid it. A silent hotfix converts one incident into a permanent question about what else you don't mention. The entry can be three sentences; it cannot be zero. The exception that proves the rule: a security fix may ship quietly ahead of coordinated disclosure — but it still gets its entry when the disclosure lands.

A copy-paste hotfix entry

## Fixed: [symptom users saw] ([version]) — [date]

**Who was affected:** [versions / platforms / plans / % of users], from [when] to [when].
**What happened:** [symptom in user terms — what it looked like from outside].
**The fix:** shipped in [version] — [rolling out now / update manually / no action needed].
**What you should do:** [specific action, or "nothing — already applied"].

_We'll follow up with what caused this and what we're changing. → [post-mortem link when ready]_

Anti-patterns

  • The silent hotfix. Covered above; the most expensive option in the long run.
  • Announcing before the fix reaches users. "Fixed" while the old build is still serving traffic teaches readers your word "fixed" means "merged".
  • The jargon title. Named after the cause, in your internal vocabulary, invisible to the person with the actual problem.
  • Panic tone — or comedy. Write calm and factual. Apologize once, plainly, without theatrics; jokes land badly on people whose data pipeline is down (never joke about pain).
  • Blaming. A vendor, a dependency, an ex-employee. Readers hear "not safe to build on". You shipped it; own it, then explain.
  • Burying it in the next regular release's notes. A hotfix gets its own dated entry at the time it shipped — that's the whole point of an out-of-band release.

How this works in Wakelog

Mid-incident you don't want a CMS. With Wakelog, pass one is a single command from the terminal you're already in — wakelog post -t "Fixed: exports stuck at 99% (2.4.3)" with the body piped from stdin — and the entry is live with a permanent dated permalink you can paste into the status page, support threads, and chat. A per-project Discord or Slack webhook pushes it to subscribers the moment it publishes. Pass two is an edit to the same post: the URL never changes, the history stays honest. And because every post carries its date, your changelog doubles as the incident record your future self greps at 2 a.m.

Start your free changelog   Next: status page vs changelog →

Related guides

  • Security advisories vs changelog: how to publish a security fix
    A security fix needs two write-ups on two different clocks: the ship-day changelog entry and the full advisory. What goes in each, when a CVE is worth it, and why silent patching always backfires.
  • Incident postmortems vs changelog: what to publish after things break
    The status page says “we noticed,” the changelog says “we fixed it,” and the postmortem says “here is what actually happened and what changes.” When an incident earns a public postmortem, the anatomy of one worth reading, and the follow-through loop almost nobody closes — tracking the promised fixes back through the changelog.
  • Known issues: how to admit what’s broken (and why it pays)
    A release note is a claim that things work; the known issues section is what makes the claim believable. What qualifies, the symptom-first entry template, tracker vs curated list, where the section lives, and how to close the loop when the fix finally ships.

Last updated 2026-07-27 · All guides