What are release notes?
Release notes are documentation that describes what changed between one version of a software product and the next. They're written for your users — developers, end users, or both — and typically cover new features, bug fixes, performance improvements, and breaking changes.
Release notes appear in many places: the GitHub Releases tab, App Store "What's New", Slack announcements, email newsletters, and CHANGELOG.md files. Each platform has different conventions, audiences, and character limits — which is why most developers find them tedious to write.
Who reads release notes — and why it matters
Before writing, understand your audience:
- End users (App Store, product blog) — want to know: "What's new for me? Do I need to take action?" Write in plain language, avoid technical jargon.
- Developers integrating your API (GitHub Releases, npm changelog) — want to know: "What broke? What do I need to change?" Be precise, link to migration guides, flag breaking changes prominently.
- Internal teams (Slack, Linear, Jira) — want context on what shipped, who did it, and what to watch for in production.
The same release often needs three different versions of the same notes. ChangelogAI generates all of them from one commit list.
The anatomy of good release notes
Regardless of format, good release notes share these elements:
- Version number and date — always.
[2.4.0] — 2026-06-02 - Breaking changes first — flagged clearly, never buried
- New features — what can users do now that they couldn't before?
- Bug fixes — which specific issues were resolved?
- Performance improvements — with concrete numbers if available
- Deprecations — what's going away in a future version?
Good vs bad release notes — real examples
Release notes for different platforms
GitHub Releases
Use GitHub-flavoured Markdown. Group changes under ## Added, ## Fixed, ## Changed. Always include the compare link v1.3.0...v1.4.0 at the bottom. Flag breaking changes at the top with ⚡. See our GitHub release notes generator.
App Store (iOS/macOS)
Plain text, 4,000 characters max. Lead with the feature users care about most. Write in second person ("You can now..."). Group bug fixes at the end. See our App Store release notes generator.
Slack announcements
Short and punchy. Three to five bullet points maximum. Use emoji for visual scanning. Link to the full release notes for those who want detail. See our Slack release announcements guide.
Email newsletters
Conversational tone. One key feature as the hero, supporting features below. Always include a CTA to try the new feature. Subject line is half the battle — "We just shipped X" outperforms "Version 2.4 Release Notes."
CHANGELOG.md
Follow the Keep a Changelog format for consistency. Newest release at the top. Never delete old entries — they're a historical record.
The 5 rules of release notes that get read
- Rule 1: Write for the reader, not the author. You know what "refactor the auth middleware" means. Your users don't. Translate it.
- Rule 2: Be specific about bugs. "Fixed crash on login" is useless. "Fixed crash when logging in with a Google account on iOS 17.4" tells the user if this affects them.
- Rule 3: Use numbers where possible. "40% faster" is more credible and useful than "improved performance."
- Rule 4: Flag breaking changes loudly. Never bury them. A missed breaking change causes production incidents and support nightmares.
- Rule 5: Publish on the day you ship. Release notes written a week after the release are half as useful and twice as hard to write.
The shortcut: The hardest part of release notes is the blank page. Paste your commit log into ChangelogAI and get a first draft in seconds — then edit down to something great rather than writing from scratch.
Release notes templates
See our full library of release note templates for GitHub, App Store, Slack, Jira, and more — ready to copy and use.
Frequently Asked Questions
What's the difference between release notes and a changelog?
A changelog is a running historical record of all changes to a product, usually in a CHANGELOG.md file following the Keep a Changelog format. Release notes are the communication you publish with each specific release — they're often more conversational and user-focused. See our full guide: /changelog-vs-release-notes/
How long should release notes be?
It depends on the platform. GitHub Releases: as long as needed, aim for scannable bullets. App Store: under 4,000 characters, ideally 200-400 for most releases. Slack: 3-5 bullets. Email: one featured item with 2-3 supporting points. The key is scannable — users skim, not read.
Should I write release notes for patch releases?
Yes, always — even for patch releases. A user experiencing the bug you fixed wants to know it's fixed. 'Fixed crash when logging in with Google on iOS 17.4' is valuable to that user. 'v1.4.1 — bug fixes' is not.
How do I write release notes when commits are vague like 'wip' or 'fix stuff'?
This is exactly the problem ChangelogAI solves. Paste your commits — vague or not — and the AI infers what likely changed and writes user-facing descriptions. You can also write your release notes from bullet points instead of git commits.
How often should I publish release notes?
Every release, no exceptions. For continuous deployment, consider weekly or bi-weekly batched release notes rather than per-deploy — that gives users a digestible summary without release fatigue.
Related Tools
Ready to stop writing release notes by hand?
Paste your commits. Get polished, publish-ready release notes in seconds. Completely free, no account needed.
Try ChangelogAI Free →