Release notes template
Release notes template and real examples
Release notes need a version, a date, and Added, Changed and Fixed lines written for users; paste your commits below to fill a template in.
Free. No signup. Runs in your browser, nothing is sent.
These are template drafts. Gin writes from your product, your voice and what has worked, every time you ship, and posts the ones you swipe right.
The format most projects follow is Keep a Changelog 1.1.0: newest version first, dates as YYYY-MM-DD, and six types of change (Added, Changed, Deprecated, Removed, Fixed, Security). Customer-facing notes reorder the same facts: the headline change first, then what to do before upgrading. Below: both templates to copy, the app store limits, and 12 real examples checked November 19, 2026.
Sample data
The release notes template
Two versions of the same release. The first is the changelog file that lives in your repo; the second is what you paste into an email, a blog post or your docs. Copy whichever you need, or both.
# Changelog
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
## [Unreleased]
## [2.4.0] - 2026-11-20
### Added
- Export any week as CSV from the Reports page (#412)
### Changed
- **Breaking:** /v1/usage returns cents, not dollars. Pin API version 2026-10 to keep dollars.
### Fixed
- The 6am email now follows your workspace time zone (#415)
[Unreleased]: https://github.com/you/app/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/you/app/compare/v2.3.0...v2.4.0Keep an Unreleased section at the top and move its lines under a version number when you ship. Keep a Changelog recommends exactly this, and the two links at the bottom let readers see the diff between versions. Leave out any section with nothing in it. If you follow Semantic Versioning, a breaking change means a new major version.
[Product] [version] · [Month Day, Year]
[One sentence: what people can do now that they couldn't before.]
New
- [Feature]: [what it does for the user]. [Where to find it.]
Improved
- [Change, with a number and its scope if there is one.]
Fixed
- [The situation that was broken, said so the person who hit it recognizes it.]
Before you upgrade
- [Breaking change: who it affects, and how to keep the old behavior.]
[Link to the docs or the full changelog]The customer version drops PR numbers and internal wording and leads with one sentence a user would repeat to a colleague. "Before you upgrade" goes last but is never optional: it's the line that saves someone a broken build.
Release notes format: what each part is for
Read twenty changelogs in a row and the good ones share a few habits:
- A date and a link of its own. Keep a Changelog lists it as a principle: "Versions and sections should be linkable." Linear gives every entry its own URL.
- The change in the first sentence, from the user's side. "You can now talk with your agents in a realtime voice call" beats a product name followed by a version number.
- Where to find it. Raycast names the exact settings path; Linear names the tab.
- The next question, answered. Linear says you need an API key, not a ChatGPT or Claude subscription. Vercel says read pricing is unchanged.
- Numbers with a scope. "Up to 6x faster" for cold reads is a claim a reader can trust. "Way faster" isn't.
- Breaking changes under their own heading, with a way out. Keep a Changelog: "If you do nothing else, list deprecations, removals, and any breaking changes in your changelog."
One shortcut to avoid, in Keep a Changelog's words: "Using commit log diffs as changelogs is a bad idea: they're full of noise." A commit message is written for the next developer. A release note is written for the person who uses the thing. The free tool above sorts commits into the template, but the rewrite from one reader to the other is still yours.
Release notes examples: 12 real entries, by pattern
| Product | Date | Pattern | Entry |
|---|---|---|---|
| Linear | Nov 12, 2026 | One big feature | Bring your own key |
| Raycast | Nov 18, 2026 | One big feature | Raycast MCP (v2.13) |
| Cursor | Nov 6, 2026 | One big feature | Voice chat with agents |
| Tailwind CSS | May 8, 2026 | Roundup | Tailwind CSS v4.3 |
| Claude Code | Nov 17, 2026 | List of fixes | v2.1.327 |
| Bun | Nov 19, 2026 | Security release | Bun v1.4.5 |
| Supabase | Nov 4, 2026 | Breaking change | Supabase CLI v3 |
| GitHub | Nov 2, 2026 | Breaking change | pull_request_target blocked by default |
| Stripe | Nov 18, 2026 | Breaking change | Nullable microdeposit arrival dates |
| Zed | Nov 18, 2026 | Breaking change | Zed 1.29.1 |
| Raycast | Nov 13, 2026 | Numbers-led | New Calculator (v2.12) |
| Vercel | Nov 18, 2026 | Numbers-led | Drives up to 6x faster |
Checked 2026-11-19.
One big feature
The best get the what and the where into two sentences, then stop. Raycast 2.13: "Introducing Raycast MCP, a local server that lets agents like Claude, Codex and Cursor use Raycast. Turn it on in Settings → MCP → Raycast MCP Server." Tailwind's v4.3 post shows a roundup can still sound like a person: it promises "all the v4.2 stuff we shipped while forgetting blogs existed."
A list of fixes
Each line says what works now, not "Fixed a bug where". Claude Code's v2.1.327 starts every line with a verb and names the command: "Added claude mcp add-json <name> - to read the server's JSON from stdin, so tokens can stay off the command line." Bun v1.4.5 opens with the one fact a security team needs: "This is a security release."
A breaking change
All four give a date, say who is affected and offer a way to keep working. GitHub puts the date first: "Starting December 2, 2026, GitHub Actions will block pull_request_target events by default in all public repositories." Stripe adds a heading most notes skip, "Why is this a breaking change?" Zed quotes the one setting that restores the old behavior. Supabase ends its summary with the action: "Update your CI before you upgrade, or pin v2."
Numbers-led
A number in the first line is the easiest hook there is, if it has a unit and a scope. Raycast 2.12: "It's 60x faster and uses 65% less memory." Vercel puts "up to" in front of its 6x and adds "Read pricing is unchanged."
Changelog examples and the posts they became
A good entry is also the start of a good post. Each pair below is a short quote from a real changelog and a post we wrote from it to show the format. These companies didn't post them, and no results are implied.
You can now bring your own key to Linear’s cloud coding agent and use your existing provider credits and negotiated rates.
You’ll need an API key, not a ChatGPT or Claude subscription.
Linear's coding agent can now run on your own model key.
Use the credits and rates you already have. Your provider bills the tokens; the sandbox still uses Linear AI credits.
You need an API key, not a chat subscription.
The change and the reason to care fit in one sentence. The last line kills the first support ticket before anyone files it.
Starting December 2, 2026, GitHub Actions will block pull_request_target events by default in all public repositories unless an applicable Actions event policy explicitly allows them.
From December 2, GitHub Actions blocks pull_request_target by default in public repos.
If a workflow needs it, allow it in an Actions event policy. Private and internal repos are not affected.
A breaking change makes the most useful post of all: the date, who is affected, who isn't, and the fix.
Vercel Drives now reads files up to 6x faster.
All drives get this update automatically, with no SDK upgrade or configuration changes required.
Read pricing is unchanged.
Vercel Drives now reads cold files up to 6x faster.
A new read-ahead algorithm loads data before your code asks for it.
No SDK upgrade. No config. Same read pricing.
The last two lines answer what every speedup raises: do I have to do anything, and will it cost more?
Diffs, Linear’s fast and focused review experience, is now available for iOS and Android.
You can now review code from your phone in Linear.
Diffs is on iOS and Android. From the Reviews tab you can follow a Guided Review, start on mobile and finish on desktop, and merge approved changes.
Update the Linear app to try it.
It names the tab to open and what you can do there, so the reader can picture it on their own phone.
The rules behind these drafts: lead with what the reader can now do, keep the one detail that makes it real (a path, a command, a number), write each channel in its own shape, and skip what nobody outside the team cares about. Our LinkedIn post generator applies them to a pasted release, three drafts at a time.
App store release notes: the limits
An app's release notes have a second home: the store's update list, where the first line is all most people read.
- App Store, What's New in This Version: up to 4,000 characters, required for every version after the first, per Apple's App Store Connect reference.
- App Store, promotional text: 170 characters above your description, changeable "without requiring an updated submission". Use it for features that ship from the server.
- Google Play: 500 Unicode characters per language, each language wrapped in tags like <en-US>.
Slack shows the range in its own store history: exact fixes like "Tapping a name in a message shared from another workspace now opens the author's profile", and on October 21, 2026, "Nothing to report this time." Honest beats "Bug fixes and performance improvements", which tells nobody whether their bug is gone.
Changelog vs release notes
The two words get used as if they mean the same thing, but they serve different readers.
- A changelog is, in Keep a Changelog's words, "a curated, chronologically ordered list of notable changes for each version of a project". The first template above is one.
- Release notes tell the story of one release for the people who use it: a headline, why it matters, how to upgrade. The second template is one.
- App store notes are release notes squeezed into a store field, read by someone deciding whether to tap Update.
Most teams need the changelog for developers and the release notes for everyone else, written from the same list.
Where Gin fits
We make Gin, so weigh this part accordingly. Gin doesn't write or host your changelog; keep doing that, because it's the source every post comes from. What Gin does is the step after: each merged PR, release or coding-agent session arrives as a message, one model call decides which channels it deserves (a dependency bump gets none), and each channel gets a finished post as a card in a deck on your phone or the web. Swipe right to post, left to pass.
If your releases come out of Claude Code, our Claude Code marketing guide shows the hook that sends each session's summary. And if you want the weekly rhythm around releases, the build in public guide has a cadence that starts from the same notes. For a store note or a server-side launch, send one line by hand:
gin ship "Export any week as CSV from the Reports page"X, your LinkedIn profile, Bluesky and Dev.to post directly once connected. TikTok and newsletters get a draft you send yourself. Other channels are copy and open: Gin copies the post and opens the composer.
Questions
What should release notes include?
A version and date, then the changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security, each written from the user's side. Put breaking changes where nobody can miss them, with a way to keep the old behavior or pin the old version.
What is the standard release notes format?
Keep a Changelog 1.1.0 is the most common: newest version first, ISO dates (YYYY-MM-DD), an Unreleased section at the top, and the six change types as headings. Customer-facing notes reorder the same facts with the headline change first.
What is the difference between a changelog and release notes?
A changelog is an ongoing list of notable changes for every version, usually in the repo. Release notes tell the story of one release for the people who use it: the headline change, why it matters and how to upgrade.
How long can App Store and Google Play release notes be?
Apple allows 4,000 characters for What's New in This Version, not shown for an app's first version. Google Play allows 500 Unicode characters per language. Apple's 170-character promotional text can change without a new version.
Can I generate release notes from commits?
You can sort them automatically, as the free tool on this page does: features into Added, fixes into Fixed, chores and dependency bumps dropped. Rewrite each line for users before you publish; commit messages are written for developers.
Related guides
Sources
Checked November 19, 2026. Prices and limits change; each link goes to the page we read.
- Keep a Changelog 1.1.0
- Semantic Versioning
- Linear changelog: Bring your own key (Nov 12, 2026)
- Linear changelog: Mobile Diffs (Nov 5, 2026)
- Raycast changelog: v2.13 (Nov 18, 2026)
- Raycast changelog: v2.12 (Nov 13, 2026)
- Cursor changelog: Voice chat with agents (Nov 6, 2026)
- Tailwind CSS blog: v4.3 (May 8, 2026)
- Claude Code releases on GitHub (v2.1.327, Nov 17, 2026)
- Bun blog: Bun v1.4.5 (Nov 19, 2026)
- Supabase changelog: Supabase CLI v3 (Nov 4, 2026)
- GitHub changelog: pull_request_target blocked by default (Nov 2, 2026)
- Stripe API changelog: nullable microdeposit arrival dates (2026-11-18.preview)
- Zed release notes: 1.29.1 (Nov 18, 2026)
- Vercel changelog: Drives up to 6x faster (Nov 18, 2026)
- Slack on the App Store (version history)
- Apple: platform version information (What's New, promotional text)
- Google Play Console Help: release notes
You ship. Gin posts.
Get the app, paste one message into your coding agent, and swipe through your first cards tonight.