Different releases need different shapes, not one template stretched to fit everything. A patch needs one line; a breaking change needs a migration note; a security release needs care about what stays unsaid until affected hosts have updated. Below are six templates, each with placeholder markers you fill in, followed by an illustrative example of the same template filled out.
This page is one part of a larger guide. For the whole subject in one place, see changelogs and release notes.
Which template fits which release?
| Release type | Reach for it when |
|---|---|
| Standard release | Several unrelated changes ship together, a normal week |
| Patch or hotfix | One narrow fix goes out on its own, outside the usual cadence |
| Security release | A vulnerability was patched and detail must stay limited for now |
| Breaking change | Something a reader relies on works differently after this release |
| Major version | The release is the headline, not a routine entry in a list |
| In-app or email notice | The full entry lives elsewhere and this is the short version that reaches someone directly |
The standard release template
Most releases are this one: a handful of changes, grouped by kind, each stated as an effect rather than a mechanism.
## [VERSION], [DATE]
**New**
- [what the reader can now do]
**Improved**
- [what got better, stated as an outcome]
**Fixed**
- [what no longer happens]Filled in:
## 2.6.0, 20 August 2026
**New**
- You can now assign a request to a teammate.
**Improved**
- Search returns results as you type.
**Fixed**
- Duplicate votes no longer appear on a request.The patch or hotfix template
A patch usually fixes one thing and does not need three headed sections to say so. One line, dated, is the whole entry.
## [VERSION], [DATE] (patch)
- [the one thing this release changes]Filled in:
## 2.6.1, 21 August 2026 (patch)
- Exporting a board with zero votes no longer fails.The security release template
The habit worth keeping here: confirm a fix shipped and recommend updating, without describing the vulnerability itself while anyone is still exposed.
## [VERSION], [DATE] (security)
**Security**
- A fix shipped for an issue in [affected area]. No
further detail is published while it may still
affect hosts that have not updated.
- Upgrading is recommended for all users.Filled in:
## 2.6.2, 22 August 2026 (security)
**Security**
- A fix shipped for an issue in the export endpoint.
No further detail is published while affected
hosts are still updating.
- Upgrading is recommended for all users.The breaking-change template
State plainly what stops working the old way, what replaces it, and where the full steps live. A break like this is also the only thing semantic versioning reserves a major version bump for, which is why the filled example below jumps to 3.0.0. A reader deciding whether to update now needs all three before they can make that call.
## [VERSION], [DATE] (breaking change)
**Breaking**
- [what stops working the old way]
- [what to do instead, in one line]
- Migration guide: [link]
**New**
- [what the change makes possible]Filled in:
## 3.0.0, 25 August 2026 (breaking change)
**Breaking**
- The old /api/v1/export endpoint is retired.
- Use /api/v2/export, same response shape.
- Migration guide: [link]
**New**
- Exports now include comments, not just posts.The major version template
A major version earns a headline the way a standard release does not, but the smaller changes riding along with it still deserve their own lines rather than getting folded into the headline's prose.
## [VERSION], [DATE]
[One line describing the release in plain terms.]
**Headline changes**
- [the one or two things worth a reader's attention]
**Also in this release**
- New: [smaller addition]
- Improved: [smaller improvement]
- Fixed: [smaller fix]
Full changelog: [link]Filled in:
## 4.0.0, 1 September 2026
A new roadmap view, and a faster search index.
**Headline changes**
- Roadmap board: drag requests between stages.
- Search now returns results as you type.
**Also in this release**
- New: CSV export for any board.
- Improved: emails send within a minute of a status
change, not up to an hour later.
- Fixed: long titles no longer overflow on mobile.
Full changelog: [link]One payment, no subscription, unlimited products.
The in-app or email notice template
This one is not the full entry, it is a pointer to it: one sentence a reader can absorb in passing, and a link to the page that has the rest.
Subject: [product] [version] is here
[One sentence: what the reader can now do.]
[Optional second sentence: the next most useful
change.]
See what else changed: [link to full changelog]Filled in:
Subject: Docket 2.6 is here
You can now assign a request to a teammate, and
search returns results as you type.
See what else changed: [link to full changelog]Are you describing the change, or what the reader can now do?
This is the single biggest improvement most release notes could make, and it is a different question from which template to use. "Refactored the assignment logic" describes the change. "You can now assign a request to a teammate" describes what the reader can now do. Both sentences might be true of the same release, and only one of them belongs in a note written for someone who has never seen the code.
The test is simple: read the entry back and ask whether it names an action the reader can take or a feeling they will notice, rather than a part of the system that moved. "Optimised the save handler" names a part of the system. "Typing no longer causes a lag before your changes save" names what the reader will notice. The second sentence works even for a reader who has no idea what a save handler is, which is the whole point.
This applies inside every template above, not instead of them. A breaking-change entry still has to name the action, "use /api/v2/export instead," not just the fact that something moved. A security entry still has to say what upgrading gets you, "the fix is included," even while withholding the mechanism. The template decides the shape; this rule decides whether each line inside it is doing its job. For the fuller version of this idea, including a table of weak-to-strong rewrites, see how to write release notes.
Frequently asked questions
Can these templates use categories other than New, Improved and Fixed?
Yes. The three used here are a common, simple default, not a requirement. Some teams use the six-category Keep a Changelog convention instead, Added, Changed, Deprecated, Removed, Fixed and Security, and the templates above work the same way with either set: pick one, and use it consistently release after release.
Does every release need a version number?
No. A product shipping continuously without formal version numbers can date each entry instead and drop the version marker entirely from the templates above. What matters is that every entry has some stable identifier, a version or a date, that a reader can reference later.
What if a release fits more than one template, such as a breaking change that is also a major version?
Combine them. Keep the breaking-change section's three lines, the retired behaviour, its replacement, and a migration link, and add the major version's headline framing around it. The templates are components, not mutually exclusive forms.
How short can a release note actually be?
As short as the patch template above: one dated line naming the one thing that changed. A release note is not required to have multiple sections or multiple entries; it is required to tell the reader what changed for them, and sometimes that takes one sentence.
Should the in-app or email notice repeat the full changelog entry?
No, that defeats its purpose. The notice exists to reach someone who is not going to visit a changelog page on their own, so it should say the one sentence that matters and link to the rest, not attempt to reproduce every section from the full entry inline.