Known issues: how to admit what’s broken (and why it pays)

Every release note is a claim: here is what works now. The known issues section is the part of the document that makes the claim believable. A changelog that only ever reports victories reads like a brochure; the moment a reader hits a bug it never mentioned, every other sentence gets re-read with suspicion. A changelog that says “this is broken, here is who it affects, here is what to do until we fix it” has done something no amount of polish can do — it has proven that when something is wrong, this page will say so.

That is why known issues are the cheapest trust available to a software team. They cost one honest paragraph. This guide covers what qualifies as a known issue, how to write one entry well, where the section should live, how to retire an issue without it looking like a cover-up, and the handful of ways teams turn an honesty device into its opposite.

Why publishing known issues pays

The case is practical, not moral:

  • The reader will find the bug either way. The only question is whether they find it in your release notes — with scope and a workaround — or in a forum thread titled “is anyone else seeing this?” The first reader thinks they know, and there’s a workaround. The second thinks it’s broken and they don’t even know. Same bug, opposite conclusions about your team.
  • It deflects support load at the exact moment of need. People search before they file. A findable known-issue entry with a workaround is a ticket that never gets opened — and a duplicate report that never needs triaging. This is the same search-at-the-moment-of-pain behavior that makes symptom-first hotfix entries work.
  • It buys patience. Users tolerate a listed bug for weeks; they tolerate a denied one for about a day. The acknowledgment is most of the relief — it converts “am I going crazy?” into “they’re on it.”
  • It protects the upgrade decision. For readers deciding whether to take a release — operators especially — a candid known-issues list is information they can plan around. Games learned this in public: patch notes with a known-issues block get dramatically less rage than patches whose bugs surface only in player threads.

What qualifies (and what doesn’t)

A known issues section only works if it is curated. The operational definition — a known issue, for release-notes purposes, is a problem that is:

  • User-visible. Someone using the product normally can hit it and notice. Flaky internal tests, refactors-in-progress, and things only your dashboards can see don’t belong.
  • Present in the release you are shipping. The section describes this version’s rough edges, not your backlog.
  • Not fixed yet — and, implicitly, not about to block the release. If it were bad enough to block, you would have blocked. Saying so is allowed: “we shipped anyway because the fix is riskier than the bug” is a legitimate, adult sentence.

The threshold question: would a reasonable user hit this and wonder whether you know? If yes, list it. If it takes three preconditions and a full moon, it lives in the tracker, not the notes. And one hard exclusion: known security vulnerabilities are not known-issues content. An unfixed vulnerability follows a disclosure process — private handling, then an advisory — not a bullet that tells attackers where to aim.

Anatomy of a good known-issue entry

One entry, four parts, in this order:

### Known issues

- **Exports over ~10,000 rows can time out.** Affects CSV and JSON
  exports on large workspaces; the export appears to hang, then fails
  after 60 seconds. Workaround: filter to a date range and export in
  parts. Tracking: #4182. Fix scheduled for 2.4.2.
- **Dark mode: chart labels are illegible on Windows.** Cosmetic;
  Windows only, all browsers. No workaround yet. Tracking: #4190.
  • Symptom first, in the user’s words. Name what the reader sees — “the export appears to hang” — not the internal cause. The entry exists so a person mid-symptom can recognize it; the same symptom-naming discipline as fix entries, pointed in the other direction.
  • Scope, honestly. Which platforms, which versions, roughly how many people. “Windows only, all browsers” lets most readers exhale and move on; that exhale is the point. Vague scope (“some users may experience…”) protects nobody and reads as legal hedging.
  • Workaround — or the honest absence of one. “No workaround yet” is a complete, respectable sentence. An entry that omits the line entirely leaves the reader to guess.
  • A tracking link and, when you have one, a horizon. The tracker issue is where the conversation lives; the date or version is a promise, so only write one you can keep — “fix scheduled for 2.4.2” beats “soon,” and nothing at all beats a date you’ll miss.

Register matters as much as structure. The right voice is calm and precise — no apology theater (“we deeply regret any inconvenience” says nothing), and no minimizing in the other direction: calling something “minor” that eats a user’s afternoon costs more trust than the bug did. Severity honesty runs both ways; state what it does and let the reader judge the size (the tone guide covers this register in depth).

Known issues vs the bug tracker

“Why maintain this at all? The tracker is public.” Because the tracker is the universe and the known-issues section is a map. A public tracker has hundreds of open items — duplicates, wishlist entries, can’t-reproduce ghosts — and asking a user mid-symptom to search it is asking them to do your triage. The known-issues section is the short, editorial answer to one question: of everything open, what is a normal user of this release actually likely to hit?

So: curate the list, link each entry to its tracker issue for the conversation and the subscribe button, and never paste the tracker into the notes. A raw issue dump is the known-issues version of the commit-dump changelog — technically complete, practically unreadable, and a signal that no human decided anything.

Where the section lives

Two homes, different clocks — most products eventually want both:

  • Per-release, inside the entry. A “Known issues” block at the bottom of the release’s notes, describing that version’s state at ship time. This is release-scoped and effectively frozen: it records what you knew when you shipped. Firmware and driver teams treat this block as mandatory — when rollback is hard, the reader must know the rough edges before updating, and app-store screens deserve the same courtesy since store updates can’t be un-shipped quickly either.
  • A living known-issues page. Product-scoped, edited in place, always current: what is broken right now, regardless of which release introduced it. This belongs in your docs at a stable URL, with dated updates on each entry so returning readers can see movement. Release entries link to it; it links back to the releases that introduced and fixed each issue. (It is not a status page — status pages answer “is it down?”; the known-issues page answers “is this bug mine?”)

Closing the loop

The known-issues section has a lifecycle, and the exit matters more than the entrance. When the fix ships:

  • The fix entry names the issue it closes. “Fixed: exports over 10,000 rows no longer time out (known issue since 2.4.0).” The reader who has been living with the workaround is the most attentive reader that release will have — tell them directly.
  • The original entry gets a pointer, not deletion. Append “Fixed in 2.4.2 →” with a link. An issue that silently vanishes from the list is indistinguishable from a cover-up, and the reader on the old version still needs the entry to be true for them.
  • The living page moves the item to a dated “recently fixed” tail for a few weeks. People who bookmarked the workaround deserve to learn it is no longer needed.

One more exit exists: we are not going to fix this. Saying so — with the reason — is far better than letting an entry rot on the list for two years. A “won’t fix” with rationale closes the question; an eternal known issue becomes a monument to it.

The empty list

Resist boilerplate. “No known issues” is a strong claim, and readers will test it against reality; write it only when it is true, and omit the section otherwise. A template that always prints the heading trains people to skip it — the delete-sections-that-don’t-apply rule applies here with extra force, because this is the one section whose credibility is its entire value.

Anti-patterns

  • The silent known issue. You knew at ship time; the forums found out first. Every future “fixed” entry now gets read as “finally admitted.”
  • The tracker dump. Forty auto-listed open issues. Nobody can tell which three matter; the section stops being read.
  • Weasel scope. “Some users may experience issues with sync.” Which users? What issues? An entry that can’t be matched to a symptom comforts the lawyer and helps no one.
  • The workaround that became the fix. The entry has said “workaround: export in parts” for eighteen months. A workaround is a loan, not a payment.
  • The disappearing issue. Removed from the list with no fix entry anywhere. Readers assume the worst, and they are usually right to.
  • Apology inflation. Three sentences of regret, zero of scope or workaround. Contrition is not information.

Doing this with Wakelog

Wakelog supports the whole loop without any special machinery: entries are markdown, so a ### Known issues block drops into any release post; posts are editable at a stable URL, so appending “Fixed in 2.4.2” later is the same two-pass edit-the-entry pattern the hotfix guide recommends, with the permalink staying valid everywhere you shared it. Public-page search means a user typing their symptom finds the entry, and the fix post that names it, in one query. Honest caveat: Wakelog has no structured known-issues model — the section is a writing convention, not a feature, and a living always-current page belongs in your docs (see docs vs changelog) with your release entries linking to it.

Keep a changelog people believe   Next: beta and early-access release notes →

Related guides

Last updated 2026-07-31 · All guides