Software Release Notes Template: Format and Examples

1. What release notes are for

Release notes describe what a specific app version brings: new features, fixes, removed parts and the steps a user or administrator has to take. Customers, support and consultants read them, not just developers.

In practice, the description of changes is scattered across commits, pull requests, Slack and email. Support then can't tell whether a reported bug is already fixed in the customer's version. The customer never gets to the list of changes at all.

2. Release notes format: a template to copy

The template follows the change types from Keep a Changelog. Leave out empty sections and keep the same order for every release.

# <App name> <version>
Release date: YYYY-MM-DD

## Summary
One or two sentences: what this release brings and who it affects.

## Action required
- Steps before or after upgrading (migration, new setting, restart).

## Added
- New feature, described from the user's point of view (#ticket)

## Changed
- Change in how an existing feature behaves

## Fixed
- What didn't work and in which situation (#ticket)

## Removed and deprecated
- What ends in this release or will end in the next one

## Security
- Fixed vulnerabilities (without exploitable details)

## Known issues
- What doesn't work yet in this release and how to work around it

3. Sample software release notes

Here's the template filled in for a minor release of an internal app. Every item describes the effect on the user, not the change in the code.

# Invoicing 2.4.0
Release date: 2026-10-19

## Summary
Bulk PDF export of invoices and a VAT rounding fix for credit notes.

## Action required
- Administrators: run the database migration after upgrading (npm run migrate).

## Added
- Bulk export of selected invoices into a single PDF (#412)

## Changed
- The invoice list is sorted newest first

## Fixed
- Credit notes with multiple items rounded VAT off by 0.01 (#398)

## Known issues
- Exporting more than 500 invoices takes longer than a minute

4. Release notes best practices: what to include and what to leave out

Good release notes answer three questions: what changed, does it affect me and do I need to do anything. Everything else belongs in the commit history.

5. Release notes in Confluence, GitHub Releases and CI/CD

In Confluence, save the template as a page template and create a new page for every release. On GitHub, automatically generated release notes list the merged pull requests since the previous tag. That's a good starting point, but someone still has to rewrite it in the user's language.

In a CI/CD pipeline, you can build the notes from the commits between two tags and send them straight to AboutTheApp. The GET /integrations/installations/latest endpoint returns the version most recently deployed for a given customer and environment, so you know which version to count changes from.

1. 1

   Find the deployed version

   GET /integrations/installations/latest with the product alias, customer alias and environment returns the latest installation.

2. 2

   Build the notes

   Write a short summary of the changes from the commits or pull requests between the deployed version's tag and the new tag.

3. 3

   Send the version with its notes

   POST /integrations/versions with the product alias, version number and a changelog field adds the version to the product's version catalog or overwrites the notes of an existing version.

4. 4

   Record the deployment

   POST /integrations/installations assigns the version to a specific customer and environment. You'll find the CI key and ready-made curl commands in your account settings in AboutTheApp.

6. Where customers should see release notes

Release notes only help if the customer finds them next to the version they use. In AboutTheApp, every version in the product's catalog has its own changelog. The About box in your app shows the current version with its notes and the About page has a Product Versions tab with the latest versions and their changelogs. If you pass your build's version in the About box's version attribute, it shows the notes for exactly the version that's running, as long as that version is in the catalog and is public or unlocked.

If you run the app for several customers, the customer's About page shows the deployment history for that customer in the Environments & Versions tab, with the notes for every deployed version. The customer sees the changes in their version, not in the newest one.

A version's changelog in AboutTheApp supports basic Markdown: headings, bullet and numbered lists, bold, italic, code and links. You can paste the template above as is. The About box in your app shows the beginning of the notes with a link to the full text on the About page.

Frequently asked questions