Short answer
A good release notes template has a version or date, a one-line summary of the biggest change, then grouped entries: Added, Changed, Deprecated, Removed, Fixed and Security, as Keep a Changelog recommends. Write each entry as what the user can now do, link to docs, flag breaking changes first, and use semantic version numbers (MAJOR.MINOR.PATCH) if you ship an API or package.
Most release notes fail in one of two ways. Either they're a pasted commit log ("fix: null check in useInvoiceSync") that only the team understands, or they're a marketing post so vague that a customer can't tell whether the bug they reported got fixed.
The release notes template below sits between those. It works for a SaaS product's monthly update and for a library's versioned CHANGELOG.md, and it borrows the structure from Keep a Changelog, the most widely copied convention for this. After the template come four public changelog examples and what each one does better than most.
Release notes vs a changelog: who each one is for
A changelog is the complete, versioned record: every notable change, in order, newest first. Developers and admins read it when something breaks or before they upgrade. Release notes are the readable story of one release, written for the people who use the product, usually with a headline feature, a screenshot or short video, and a link to the full changelog.
Plenty of teams publish one page that does both, and that's fine. Just decide who the first screen is for. If your users are developers integrating an API, lead with breaking changes. If they're operations managers using a web app, lead with the feature that saves them time this week.
- Changelog: complete, terse, versioned, stable URLs per release. Optimized for scanning and searching.
- Release notes: selective, written in the user's words, with visuals. Optimized for adoption of the new thing.
- Both: dated, newest first, and honest about what was removed.
A release notes template you can copy
Copy the lines below into your docs tool, blog or CHANGELOG.md and replace the brackets. Delete any category that's empty for this release; an empty "Security: none" heading adds nothing.
Customer-facing release notes template
- Title: [Feature name] is here, or What's new in [Product], [Month Year].
- Date and version: [YYYY-MM-DD] · [v2.4.0] (leave the version off if customers never see version numbers).
- Summary, one or two sentences: "You can now [do the thing] without [the old workaround]."
- Visual: one screenshot or a 30–60 second clip of the new feature in use.
- How to use it: two to four short steps, or a link to the help article.
- Who gets it: plans, regions or roles, and whether it's on by default.
- Improvements: one line each, starting with the area ("Invoices: PDF exports now include your logo").
- Fixes: one line each, describing the symptom the user saw, not the code that changed.
- Heads-up: anything deprecated or removed, with the date it stops working and what to use instead.
Developer changelog template (Keep a Changelog style)
- ## [Unreleased]: collect changes here as they merge, then move them under a version on release day.
- ## [1.4.0] - 2026-10-29
- ### Added: new endpoints, options or features.
- ### Changed: changes to existing behavior, breaking ones marked BREAKING at the start of the line.
- ### Deprecated: still works, will be removed; say in which version.
- ### Removed: gone in this release.
- ### Fixed: bug fixes, with issue links.
- ### Security: vulnerabilities fixed, with advisory IDs where you have them.
Fill in the template the same way every time. Readers learn where to look, and a consistent shape makes it easy to turn the top entry into a social post or a short release notes video.
Keep a Changelog categories and semantic versioning
Keep a Changelog 1.1.0 groups changes into six types: Added, Changed, Deprecated, Removed, Fixed and Security. It asks for an entry for every version, the latest version first, dates written as YYYY-MM-DD, and an Unreleased section at the top so people can see what's coming. It also names the anti-patterns: dumping commit log diffs, and leaving out deprecations. Its blunt advice is that if you do nothing else, list deprecations, removals and breaking changes.
Semantic Versioning 2.0.0 gives the numbers meaning. In MAJOR.MINOR.PATCH you increase MAJOR for incompatible API changes, MINOR for backward-compatible new functionality and PATCH for backward-compatible bug fixes. Bumping MINOR resets PATCH to 0; bumping MAJOR resets both.
- 0.y.z means initial development: the spec says anything may change at any time, so don't promise stability before 1.0.0.
- Pre-releases add a hyphen and identifiers, such as 2.0.0-beta.1, and rank below the normal 2.0.0.
- Semver is for things with a public API: packages, SDKs, CLIs. A web app that ships daily can date its notes instead and skip version numbers.
One practical rule we use: if a release needs a MAJOR bump, its notes need a migration section with before-and-after code. A breaking change without upgrade steps turns into support tickets within the hour.
Changelog examples worth borrowing from
These four public changelogs were checked on October 29, 2026. They serve different readers, which is exactly why they're useful to compare.
| Example | Who reads it | What it does well | What to borrow |
|---|---|---|---|
| Linear changelog (linear.app/changelog) | Product teams using the app | Each dated entry opens with a short story about the headline feature, with visuals, then ends with Fixes and Improvements lists grouped by product area | Lead with one feature, then batch the small stuff by area |
| GitHub Changelog (github.blog/changelog) | Developers and admins | Every entry carries one label (Release, Improvement or Retired), topic tags you can filter, and an RSS feed | A type label on every entry, and a feed people can subscribe to |
| Stripe API changelog (docs.stripe.com/changelog) | Developers integrating an API | Changes sit under named, dated API versions, each marked Breaking or Non-breaking with the products it affects | Say plainly whether each change breaks anything |
| Vercel changelog (vercel.com/changelog) | Developers deploying apps | Short entries, each with a title, a one- or two-sentence description, often the names of the people who built it, and a link to a full post | Keep the index scannable and put detail one click away |
| GitHub auto-generated release notes | Maintainers of a repository | Builds notes from merged pull requests, contributors and a full-changelog link, grouped by labels set in .github/release.yml | Generate the draft, then rewrite the top lines for humans |
Notice what none of them does: paste raw commit messages. Even GitHub's own generator groups pull requests by label so a person can edit the result before publishing.
How to write release notes people actually read
Write from the user's side of the screen. "Added bulk-edit endpoint" is a changelog line; "You can now update 500 invoices at once from the list view" is a release note. Both can exist, but the second one is what gets the feature used.
Keep each line to one change and one sentence. If an entry needs a paragraph, it deserves its own heading and probably its own help article.
- Put the most valuable change first, not the one that took longest to build.
- Name the symptom in fixes: "Exports no longer time out on files over 10 MB" tells the person who hit it that they can stop waiting.
- Give every release its own URL so support can link to it, and link each entry to the doc that explains it.
- Say who gets it. Nothing annoys a customer faster than reading about a feature their plan doesn't include.
- Publish on a rhythm (weekly, every two weeks, monthly) so people know when to check.
- Never surprise anyone with a removal. Announce the deprecation in one release and the removal in a later one, with dates.
Adding a short video to your release notes
A 30–60 second clip of the headline feature does more than three paragraphs of description, because the reader sees where the button lives. Keep it silent-friendly with captions, show the feature being used on realistic data, and end on where to find it. Our feature announcement video guide covers structure and length.
The catch is upkeep: a screen recording goes stale the next time the UI changes. If you make videos for most releases, DemoVexa builds a what's-new video from your product's code folder, recreating the real UI in code, and you rebuild it from the latest code instead of re-recording. For a one-off clip, a quick screen recording is still the faster choice. The GitHub release to video workflow shows how teams tie this to their release process.
Questions
How often should you publish release notes?
Publish them on the same rhythm you ship to customers, and keep that rhythm predictable. Weekly or every two weeks suits products that deploy continuously; a monthly roundup works if individual changes are small. Security fixes and breaking changes get their own note the day they ship.
Should release notes include bug fixes?
Yes, include fixes that a user could have noticed, described by the symptom they saw. Leave out internal refactors and fixes to code that never reached customers; they belong in commit history, not release notes.
What version number should a first release use?
Under Semantic Versioning, use 0.y.z while the public API is still changing and 1.0.0 once people depend on it in production. The spec suggests 0.1.0 as the first development release. Products without a public API can use dates instead of version numbers.
Can release notes be generated automatically?
You can generate a first draft automatically, for example with GitHub's auto-generated release notes, which list merged pull requests and contributors grouped by label. Treat the draft as raw material: rewrite the top entries in the user's words before publishing.
Make product videos from your code
DemoVexa reads your app's code, writes the script, adds a voiceover and animates your real screens in 16:9, 9:16 and 1:1. Try it on your own product: 14 days free, no card.
Sources
- Keep a Changelog 1.1.0 (checked 29 October 2026)
- Semantic Versioning 2.0.0 (checked 29 October 2026)
- GitHub Docs: Automatically generated release notes (checked 29 October 2026)
- Linear changelog (checked 29 October 2026)
- GitHub Changelog (checked 29 October 2026)
- Stripe API changelog (checked 29 October 2026)
- Vercel changelog (checked 29 October 2026)
DemoVexa publishes this guide and makes a product video app, so we have a stake in the topic. Facts about other products and platforms come from the sources listed, on the dates shown, and can change. Corrections are welcome through our contact page.