Release notes
reh-LEES nohts
A document accompanying a software release that describes new features, improvements, bug fixes, and known issues.
Release notes describe what is new, what is fixed, and what to watch out for in a software release. They are longer and more descriptive than a changelog entry. Release notes explain not just what changed but why it matters and how to use new features.
For major releases, release notes serve as both documentation and marketing. A well-written release note for a major feature can drive adoption more effectively than a separate blog post because it reaches developers at the moment they are checking for updates.
Release notes should be honest about known issues. Developers respect transparency. 'Known issue: memory usage increases under sustained load. Fix planned for the next release.' is better than discovering the issue in production.
Examples
Release notes for a major version.
v3.0 Release Notes: 10 new features described with screenshots and code examples. 5 breaking changes with migration guides. 15 bug fixes. 3 known issues. Performance benchmarks showing 40% improvement. The release notes are a 2,000-word document that developers read as a guide to upgrading.
Release notes drive feature adoption.
The release notes highlight a new caching feature with a before/after performance comparison. Developers who read the notes are 3x more likely to enable the feature than those who discover it through the dashboard.
Release notes handle a sensitive fix.
A security patch is released. The release notes describe the vulnerability at a high level (without providing exploitation details), the fix, and what customers should do: 'Update immediately. No action is required beyond updating. Customer data was not affected.'
In practice
Read more on the blog
Frequently asked questions
Who writes release notes?
Typically the product manager or technical writer, with input from engineering on technical details. DevRel can add context about how features address community feedback. The best release notes combine technical accuracy with clear, accessible writing.
Should release notes include screenshots?
Yes, for UI changes and new features. A screenshot shows the feature faster than words can describe it. For API changes, include code samples instead. The goal is to show developers exactly what changed in the format they will encounter it.
Related terms
A record of all notable changes to a product, published regularly to keep developers informed about new features, fixes, and breaking changes.
Written resources that explain how to use a product, including guides, tutorials, API references, and troubleshooting information.
A dedicated website that centralizes all developer resources: documentation, API reference, SDKs, sample code, and community links.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.