Bug fix release notes: how to write entries people use

Good bug fix release notes describe what the user saw go wrong, not what the code did wrong. Each entry says who was affected, since when, whether the fix is complete, and whether the reader needs to do anything, even if that is only “no action needed”.

Most teams copy a line from the commit message. The table shows six rewrites, and the sections after it explain the rules.

How do you write a bug fix entry in release notes?

Start with the symptom in the user’s words, then who was affected and since when, then the state of the fix, then the action. One or two sentences usually cover it. The code cause belongs in the pull request, where an engineer will look for it.

A reader scans for one thing: “was this me?” Four parts cover almost every entry:

1. The symptom. What appeared on screen, in the API response or on the invoice. Quote the error text if there was one, because people search for it.
2. The scope. Which plan, platform, API version or data shape. “Accounts with more than 50,000 rows” is checkable. “Some users” is not.
3. The window. Since which release or date, so a reader can decide whether yesterday’s odd result was the bug.
4. The action. Re-run, re-sync, upgrade, remove a workaround, or nothing at all.

If users built a workaround, the action line is where you tell them they can delete it.

What is the difference between a release note and a changelog?

A changelog is the complete running record of changes. Release notes are a selected, rewritten message about one release for people deciding whether to care. For bug fixes, the changelog lists every fix and the notes lead with the ones a reader could have noticed.

A tooltip typo belongs in the changelog only. A wrong tax rate on invoices belongs in both. The full split is in changelog vs release notes, and the shape of a good set of notes is in how to write release notes.

Keep a Changelog is a handy convention for the record side. It keeps “Fixed” for any bug fixes and a separate “Security” heading for vulnerabilities, which is the same split this article makes for the reader.

Is a bug fix an update?

Yes. A bug fix changes the product, so shipping one is an update. Under semantic versioning a backward compatible fix is a patch release, for example 4.2.0 to 4.2.1.

Whether the reader has to do anything is a separate question, and the note should answer it. A fix that changes what a correct caller observes is close to a breaking change, and breaking changes explains where that line sits.

When should a fix get its own entry, and when is it a minor fix?

Give a fix its own entry when a user could have noticed the bug, lost time or data to it, or built a workaround around it. Group it under a short “Minor fixes” list when nobody outside your team could have seen it. Judge it by the reader’s experience, whatever the size of the diff.

Each line in the group should still say something: “Fixed some UI issues” is a placeholder.

How do you write about a regression?

Name the release that introduced it, call it a regression, and give the release that fixes it. People who hit the bug already know it broke, so a short, direct admission serves them better than vague wording.

For example: “Search results for queries containing a hyphen came back empty in 4.1.0. This is fixed in 4.1.1. If you changed your queries to avoid hyphens, you can change them back.”

“Improved search reliability” reads as evasion to anyone who lost an afternoon to the bug. If the cause is still being confirmed, say so, as the guidance on emergency release notes puts it: never let the note sound more certain than the team is.

How do you announce a security fix?

State the severity plainly, name the affected versions and the version that fixes them, say how urgent the upgrade is, and include the CVE identifier if one exists. Publish details only once users can act on a fix, following a coordinated disclosure process when a reporter was involved.

The sequence matters: the reporter tells you privately, you ship the fix, and the public note goes out when users can protect themselves. CISA’s coordinated vulnerability disclosure process coordinates reporting, analysis and public disclosure of vulnerabilities. The CVE Numbering Authority rules govern how CVE records are assigned and published, and on GitHub a repository security advisory lets you draft the advisory privately and request an identifier.

A security entry usually carries four facts:

• What an attacker could do, in one sentence and without a proof of concept.
• Affected versions, and the version that fixes it.
• How urgent it is: “upgrade today” or “upgrade at your next release”.
• Whether you have seen exploitation, and credit to the reporter if they agreed.

Leave out exploit steps.

What should a note say about a data-loss fix?

Say what data was affected, how to tell whether yours was, and whether it can be recovered. “No action needed” is rarely true here, and the reader’s first question is “is my data gone”.

A usable entry gives the condition that lost data (“deleting a folder while a sync was running”), the window in which it was possible, a way to check (“open Trash and look for items dated 3 to 9 September”), and the recovery path. If the data cannot be recovered, say that. Contact affected customers directly too, because the release note should not be the only place someone learns their data was hit.

Why is “Bug fixes and performance improvements” a poor note?

It gives the reader nothing to act on and hides the fixes someone was waiting for. A customer who reported a crash cannot tell whether it is fixed, and a customer with a workaround cannot tell whether to remove it.

There are two honest alternatives. If a release has nothing a reader could notice, publish no notes for it and let the changelog hold the record. If it has fixes, list them in the reader’s terms:

Before:
  Bug fixes and performance improvements.

After:
  Fixed: CSV export failed for projects without tags.
  Fixed: dark mode hid the cursor in the comment box.
  Faster: the dashboard opens quicker for workspaces
  with more than 100 projects.

Where do bug fix notes come from?

They come from the pull request that fixed the bug and the report that triggered it. If the reporter’s words travel with the fix, half the symptom is written.

Feature request vs bug report explains why labelling a report correctly decides who owns it. In Changeloop, a bug reported through the widget becomes a GitHub issue labelled bug, and the changelog entry is drafted from the merged pull request and held for a person to approve before it publishes. The release notes template gives you the same entry shape for writing by hand: symptom, scope, window, action.

FAQ

What should bug fix release notes include? Each entry should name the symptom the user saw, who was affected, since which release or date, whether the fix is complete, and what the reader needs to do, including “nothing”.

Should every bug fix be listed in release notes? No. List the ones a user could have noticed, lost time to, or worked around, and group cosmetic or internal fixes under a short “Minor fixes” list. The changelog keeps every fix for anyone who needs to look one up.

How do you write release notes for a bug you introduced? Say it was a regression, name the release that introduced it and the release that fixes it, and tell readers whether they can remove any workaround. A plain statement reads better than softened wording.

How do you check release notes for a product you use? Look for a changelog or release notes page linked from the product’s help menu, footer or documentation, or in the releases tab of the repository for open source projects.

The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.

Related on changeloop: Release notes template