Release Notes Template: The Five Sections, With Examples

Almost every set of release notes contains a line like this one. "Fixed an issue where the modal would occasionally not render correctly." It is accurate. It passed review. And it is invisible to the one person who cared, the customer who wrote in three weeks ago to say the checkout window came up blank and they could not pay you.

That gap is what a template is for. Not to make the writing prettier, but to force each entry through a question the author would otherwise skip: who is this line for, and would they recognize their own problem in it. This guide gives you the five sections, worked examples of a feature, a fix, and a breaking change, a pre-publish checklist, and a copy-paste format at the bottom.

What a Release Notes Template Actually Needs

Five sections, in this order. The order does real work. The summary sits above the lists so a skimmer can leave after one line, and Changed sits at the bottom because it is the section people go looking for deliberately rather than stumble into.

1. 1

   1. Version and date

   A version number or a release name, and the date it went out. This looks like the least important line in the document and it is the one that gets referenced most, because six weeks later somebody in support needs to answer "when did that change" and the notes are the only record with a date on it that a customer can also see.

2. 2

   2. The one-line summary

   One sentence naming the most significant thing in this release. Not a list, not a paragraph, and not "various improvements and bug fixes". A reader decides here whether to keep reading, so this line is doing the entire job for most of your audience. If nothing in the release is worth a sentence, say that plainly and keep it short.

3. 3

   3. New

   Capability that did not exist before. Write each entry as something the reader can now do, not as something you built. "You can now export a report as CSV" rather than "Added CSV export endpoint". One sentence each, and link to documentation if there is any, because a new feature the reader cannot immediately find is worse than one you did not mention.

4. 4

   4. Fixed

   Defects that are now resolved, described as the symptom rather than the cause. This is the section that gets written badly most often, and the fix is a single test: would the person who reported this recognize their own bug in this line. If the answer is no, rewrite it from their side of the screen.

5. 5

   5. Changed or removed

   Anything that behaves differently than it did yesterday, including deprecations, defaults that moved, and things you took away. Be direct about breaking changes and put the migration path in the same entry. Burying a removal in a bullet halfway down is how you turn a planned change into a support incident.

How to Write Release Notes People Actually Read

The template gives you the shape. The writing is a separate skill, and it comes down to consistently choosing the reader's vocabulary over yours.

• Describe the effect, not the change

  An entry should complete the sentence "you can now" or "this no longer happens". "Refactored the notification queue" tells the reader nothing they can act on. "Notifications no longer arrive out of order" tells them whether to care. The engineering detail is not wrong, it is just written for a different audience, and that audience already read the pull request.

• Use the customer's word for the thing

  Internal names leak into notes constantly, and every one of them costs a reader. If your team calls it the entity resolver and customers call it duplicate matching, the note says duplicate matching. This sounds obvious and it is violated in almost every release note written by the person who named the component.

• One sentence, past tense, active

  Consistency in form makes a list scannable, and scannability is most of the value. Past tense for fixes and changes, present for new capability. Avoid hedges like "should now" and "improved handling of", which read as uncertainty about whether the fix worked.

• Cut the entries nobody outside can see

  Dependency bumps, internal refactors, test coverage, and infrastructure moves belong in the changelog, not the release notes. Every invisible entry dilutes the visible ones. If a reader scrolls past four lines that mean nothing to them, they stop scrolling.

The test for any line in the Fixed section is whether the customer who reported it would recognize their own bug. If they would not, you have documented the patch rather than announced the fix.

Release Notes Examples

Abstract advice about tone is easy to nod at and hard to apply, so here are three entries in the form most teams write them and the form that works, covering the three cases that behave differently.

A new feature.

Before: "Implemented bulk actions in the ticket list view (#4821)."

After: "You can now select multiple tickets and change their status, owner, or priority in one action. Select tickets with the checkbox column, then use the toolbar that appears."

The rewrite adds the thing the original assumed, which is where the feature is and how to start using it. A new capability the reader cannot locate in ten seconds produces a support ticket, not adoption.

A bug fix.

Before: "Fixed a race condition in the attachment upload handler."

After: "Fixed a problem where uploading two files quickly could leave the second one missing from the ticket. Existing tickets affected by this have been repaired."

The second version is recognizable to the person who wrote in about a missing attachment, and it answers the question they would have asked next, which is whether their old ticket got fixed too. That second sentence is the part almost nobody writes and the part that stops a follow-up email.

A breaking change.

Before: "Deprecated the v1 webhook payload format."

After: "The v1 webhook payload is no longer sent as of this release. Endpoints still expecting v1 will receive v2 fields instead, which renames ticket_id to id and nests the owner object. If you have not migrated, your webhook handler will stop matching records today. The migration guide is here."

Length is justified here in a way it is not anywhere else in the document. A breaking change entry has to state what broke, what the new shape is, what happens if you ignore it, and where the migration lives. Being brief about a breaking change is not a style choice, it is a decision to handle it in support instead.

Release Notes vs a Changelog vs a Product Changelog

These three words get used interchangeably and they are three different documents with three different audiences. Picking the wrong one is why some teams have release notes nobody reads and others have a changelog that customers find confusing.

• A changelog is complete

  Chronological, often generated from commits or merged pull requests, and it includes everything. Its audience is engineers and support staff who need to answer exactly what moved and when. Completeness is the whole point, so do not curate it.

• Release notes are curated

  Grouped by release, written for the person using the product, and deliberately incomplete. Most changelog entries never appear here. Their job is communication rather than record keeping, and they are the document this template is for.

• A product changelog is public and ongoing

  A rolling public feed on your site or docs, usually with no version numbers, updated whenever something ships. It is closer to release notes than to a raw changelog, and it suits continuous deployment teams who have nothing to batch into a version. The same writing rules apply.

The practical recommendation is to keep the changelog generated and complete, then hand-write release notes from it. Trying to make one document serve both audiences produces something too noisy for customers and too vague for engineers, and the usual outcome is that the customers leave first.

The Release Notes Checklist

Run this before publishing. It takes about two minutes and it catches the failures that are embarrassing to fix afterward.

The last item is the one that fails, and it fails for a structural reason rather than a discipline one.

Where the Fixed Section Comes From

Writing release notes is a thirty-minute job. Assembling them is not, and the difference between the two is almost entirely the Fixed section.

New capability is easy to gather, because somebody planned it and it exists as a roadmap item with a name. Fixes are scattered. A defect that shipped this week started as a customer complaint in a support inbox, became an engineering issue under a different title, got worked on by someone who never saw the original message, and closed with a commit reference. By the time you sit down to write the notes, reconstructing which shipped fixes came from real customer reports means walking backward through two tools and hoping the link between them was recorded at the time.

That table is not really about release notes. It is about whether the handoff from support to engineering left a durable link behind it, and release notes are just the moment you find out that it did not. The same gap shows up when someone tries to write a root cause analysis and cannot reconstruct who was affected, and it is the same reason closing the customer feedback loop is the step that quietly gets skipped.

For teams where support runs on HubSpot Service Hub and engineering runs on Linear, IssueLinker is what keeps that link intact. A ticket becomes a linked Linear issue in one click with the customer's own wording carried over, and when the issue closes the ticket updates, so at release time the list of shipped fixes already carries the list of people waiting to hear about them. The Linear HubSpot integration guide covers how the two-way sync works, and managing feature requests from support to engineering covers the same handoff on the New side of the notes.

Mistakes That Get Release Notes Ignored

Four patterns account for most release notes that get published and never read.

• Writing "various bug fixes and improvements"

  This phrase is a decision to say nothing. It appears when the author does not know what shipped, which means the real problem is upstream in how changes are tracked. If you genuinely cannot describe the release, publishing a placeholder trains readers that your notes carry no information, and that lesson sticks after you start writing them properly.

• Publishing the note and calling the loop closed

  The customer who filed the ticket six weeks ago does not visit your release notes page. They are waiting on a reply. The note is the source and the reply is the delivery, and treating the first as a substitute for the second is the single most common way a fix produces no goodwill at all. Our bug report reply templates cover the wording for that message.

• Inconsistent cadence

  Release notes only pay off if readers learn they can rely on them. Three detailed posts followed by two months of silence is worse than a short note every second Friday, because the value is in the habit rather than any individual entry. Pick a cadence you can hold during a busy quarter, not the one you can hold this week.

• Announcing to everyone or to no one

  Blasting every release to every user is how you get muted, and posting only to a page nobody visits is how you get ignored. Route by relevance: the note lives on the page, significant changes get a targeted message to the people affected, and breaking changes get direct contact with the accounts that will actually break.

The thread running through all four is that release notes are a communication artifact and get judged as one. The measure is not whether the document is complete. It is whether a reader finished it knowing something they can use.

Copy-Paste Release Notes Template

Here is the template in plain text. Paste it into a doc, your CMS, a Notion page, or wherever your notes live. Drop a section when a release genuinely has nothing in it rather than writing "none", because an empty heading reads as an oversight.

RELEASE NOTES

Version:            [ e.g. 2.14.0 or "Week of Mar 3" ]
Released:           [ date ]
Applies to:         [ all customers | plan or platform, if not everyone ]

SUMMARY
One sentence naming the most significant change in this release.


NEW
- [ What the reader can now do, one sentence. Link to docs. ]
- [ ... ]

FIXED
- [ The symptom the customer saw, not the code that changed. ]
- [ Note whether existing affected records were repaired. ]
- [ ... ]

CHANGED / REMOVED
- [ What behaves differently as of today. ]
- [ BREAKING: what breaks, the new shape, what happens if ignored,
    and a link to the migration path. ]

QUESTIONS OR FEEDBACK
[ Where to reply, and where to file something. ]

---
INTERNAL, NOT PUBLISHED
Customers who reported an item in FIXED:
  Ticket        Reported by        Fix shipped        Replied
  ------------------------------------------------------------
  1.
  2.

The block at the bottom is the part that makes the rest of it worth doing. Every fix in the public section that came from a real customer report has a person attached to it who has been waiting, sometimes for weeks, and a release note published without those replies going out is a fix that generated no goodwill whatsoever. Keep that list out of the published version and do not let it be the section you skip when the release is late.

Frequently Asked Questions

What is a release notes template?

What should release notes include?

What is the difference between release notes and a changelog?

How long should release notes be?

Who should write the release notes?

How often should you publish release notes?