Release notes tell customers what changed in a product version, in plain language and grouped by type: new features, improvements, fixes and what is being retired. The internal changelog records everything, including technical changes and ticket references, to provide traceability. The standard changelog format keeps every version in a single file, from the most recent to the oldest.
How to use
- Enter the product, the version (ideally MAJOR.MINOR.PATCH) and the date.
- List the changes with type, description, audience (customers or internal) and ticket reference.
- Write the release highlight and, if there is one, the action customers need to take.
- Read the warnings: technical terms in customer notes and retired items without a replacement.
- Export as Markdown for the "what is new" blog, the help centre or the CHANGELOG file.
What each field asks for
| Field | What to enter |
|---|---|
| Product | E.g. BookEasy |
| Version | Ideally in MAJOR.MINOR.PATCH format. |
| Date | Optional. The YYYY-MM-DD format works in any language. |
| Type | New, improved, fixed or deprecated. |
| Description | E.g. text reminder 2 hours before the appointment |
| Audience | Customers see it in the notes; internal stays in the changelog. |
| Reference | Ticket code (optional, hidden from customers). |
| Release highlight | The sentence that opens the notes (optional). |
| Action required | What the customer needs to do, if anything (optional). |
Example
Version 2.4.0 of a fictional booking app has 6 changes, 5 of them for customers. The notes open with the recurring bookings highlight and sum up: 2 new features, 1 improvement, 1 fix and 1 item being retired. The technical cache adjustment stays in the internal changelog only, with its ticket reference. The export in the old format appears under "being retired", with the replacement and the deadline, and an action required notice tells users to switch to CSV by 31 December.
When to use
- With every release, to inform customers without copying the ticket list.
- To keep a tidy changelog file without writing the same thing twice.
- When a feature is being retired and customers need to know what to do.
- To check that customer notes are free of technical jargon before publishing.
Frequently asked questions
What is the difference between release notes and a changelog?
Release notes are for customers: a few lines, plain language, focused on what changes for the user. The changelog is the full record of changes, including technical ones, meant for the team and for those who integrate with the product.
What is the standard changelog format?
It is an open convention for changelog files: each version becomes a "[version] - date" section, with changes grouped as added, changed, fixed and deprecated, from the most recent to the oldest.
What is MAJOR.MINOR.PATCH versioning?
It is a way to number versions: the first number goes up for changes that break compatibility, the second for compatible new features and the third for fixes only. The tool warns you when the version does not follow this format.
How do I write notes in customer language?
Say what changes for the user, not what the team did internally. Replace "API adjustment" with "the day view opens faster", remove ticket codes and keep sentences short.
How do I announce something being retired?
Say what stops working, until when, what to use instead and what the person needs to do. The tool warns you when a deprecated item gives neither the replacement nor the deadline.
How often should I publish release notes?
With every release that changes something visible to customers. Teams with continuous delivery often group changes into weekly or fortnightly notes.