Software release notes: what they are and what to include
5 min read
Software release notes are the document that accompanies a version of software and tells the reader what changed in it, who the change affects and what, if anything, they must do. They are written once per release and read by people deciding whether to upgrade, people checking whether a problem they hit is fixed, and people who support the product. Good ones are short, specific to the version and honest about anything that breaks.
| Kind | Reader | What it covers | Where it lives |
|---|---|---|---|
| Customer-facing | Users of the product | New features, fixes, behaviour changes | In-app, a changelog page, an email |
| Developer-facing | People who call your API or SDK | Breaking changes, deprecations, new endpoints | API docs, a developer changelog |
| Enterprise or IT | Administrators who roll updates out | Known issues, system requirements, migration steps | A release notes document per version |
| Internal | Support, sales, QA | What shipped, what to tell customers, what is risky | An internal channel or wiki |
What are software release notes?
They are a dated, versioned summary of one release. A release note answers three questions for a reader who was not in the room: what is different, does it affect me, and do I need to act. The full history of the project is the changelog, and the commit log is for the people who wrote the code.
The same facts can appear in a changelog entry and in release notes. The difference is selection and audience: the changelog lists every notable change, while release notes lead with the ones a reader will notice and explain them. Changelog vs release notes draws the line in detail.
What should software release notes include?
Include the version and date, a one-paragraph summary, then the changes grouped by what the reader can do with them. For each change, say what is different in the reader’s terms, who is affected and whether action is needed.
A complete set has these parts:
- Version number and release date. Use the format your tags use, so a reader can match the notes to a build.
- A summary. Two or three sentences: what this release is for, and whether upgrading needs anything from the reader.
- New features and improvements. What the reader can now do, not what the code now contains.
- Fixes. The symptom that went away and the version it started in.
- Breaking changes and deprecations. What stops working, when, and what to use instead. Put these first if there are any.
- Known issues. Anything shipped that you know is not right, with a workaround if there is one.
- Requirements and upgrade steps. Supported platforms, minimum versions, migration commands.
Leave out refactors, dependency bumps with no visible effect, and internal tickets. If a reader cannot notice the change, it belongs in the git history. How to write release notes covers wording and order.
What does a software release note look like?
Here is a short one for a made-up command-line tool. The shape matters more than the content.
## 2.4.0 (2026-10-08)
Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.
### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
with "unknown key". Rename the key; nothing else changes.
### New
- Exports stream to disk, so files over 100 MB no longer time out.
### Fixed
- Search works again for queries containing a hyphen. Broken
since 2.3.0.
### Known issues
- Windows paths longer than 260 characters still fail. Use a
shorter output directory for now.The breaking change is first, with the exact error text a reader will see, because people search for error messages. The fix names the version it broke in, so a reader can match it to when their problem started. The known issue has a workaround, which is better than silence. Release notes examples has more wording for each type of entry.
How are software release notes different for each audience?
Keep one source of truth and write a version per audience. The facts do not change, but the level of detail does. Customers want the benefit in one line, administrators want requirements and known issues, developers want exact names and versions, and support wants to know what to say when a ticket arrives.
For API products, the developer version needs the most care, because a change that is a small fix to you can be an outage for a caller. API changelog and breaking changes cover that audience. For the internal version, internal release notes describes what support and sales need that customers do not.
Where should software release notes be published?
Publish them where the reader already is when they ask the question. For a mobile app that is the store listing, where the platform provides a release notes field for each version; Apple documents how to provide release notes for builds. For a web product it is a changelog page linked from the app. For a library it is the release page and a file in the repository, as described in GitHub release notes.
Keep every version at a stable URL so support can link to it, and keep old versions. A reader on version 2.2 needs the notes for 2.3 and 2.4 as well. If you want a starting structure, the release notes template gives you headings to copy.
How long should release notes be?
As long as the change needs and no longer. A patch release can be three lines. A major release with a migration needs a page, and probably a separate migration guide linked from the notes. The test is whether a reader who skims the first screen knows if the release affects them. If they do not, move the summary up and cut the rest. Release notes best practices lists what holds up and what is habit.
FAQ
What are software release notes? They are a versioned summary of what changed in one release of a piece of software, written for the people who use or support it. They cover new features, fixes, breaking changes and anything the reader must do.
What is the difference between release notes and a changelog? A changelog is the full running record of notable changes. Release notes are a message about one release, selected and rewritten for readers deciding whether to upgrade. Many teams publish the changelog entry for a version as its release notes.
Who writes software release notes? Usually the product manager, a technical writer or the engineer who shipped the change, with someone reviewing for tone. The best results come when the person closest to the change drafts it and a second person edits it for the reader.
Do minor releases need release notes? Yes, short ones. Even a patch release should say what was fixed and whether the reader needs to act. A one-line note is better than none, because “bug fixes and improvements” tells the reader nothing.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.