When you update a program, a document template or an internal procedure, the people who use it need to know three things: what has changed, whether they need to do anything, and whether something that used to work now behaves differently. The changelog and release notes exist to answer these questions. Without them, every update becomes a small gamble.
Changelogs and release notes are not the same thing
| Changelog | Release notes | |
|---|---|---|
| Audience | People who use or maintain the project, often technical | End users, customers, non-technical colleagues |
| Content | Complete, ordered list of changes by version | The relevant news, explained through its impact |
| Form | A single file that grows over time, usually CHANGELOG.md |
One text per release |
| Tone | Concise and precise | Conversational, focused on benefits and required actions |
Many projects have both: the changelog as the complete record, release notes as communication.
It is not the commit history
The most common mistake is generating the changelog by copying commit messages. The result is a list of entries such as «fix», «update», «refactor export module», useful to developers but incomprehensible to people who use the program. The changelog describes changes from the user's point of view, not the work done.
A widespread structure
A very popular convention, known as «Keep a Changelog», organises each version by category:
- Added: new features.
- Changed: changes to existing features.
- Deprecated: features that will be removed in future.
- Removed: features that have been removed.
- Fixed: bugs resolved.
- Security: vulnerability fixes.
Versions appear from newest to oldest, each with its date in YYYY-MM-DD format, which cannot be read differently from one country to another. At the top you keep an «Unreleased» section to collect upcoming changes.
# Changelog
## [Unreleased]
### Added
- Export of the report in CSV format.
## [2.3.0] - 2026-09-30
### Added
- Date filter on the search screen.
### Changed
- The nightly backup now starts at 2:00 instead of 23:00.
### Fixed
- Accented letters in file names are no longer replaced by «?».
## [2.2.1] - 2026-08-12
### Security
- Updated the PDF reading library to a version that fixes a known vulnerability.
Version numbers
Semantic versioning uses three numbers, MAJOR.MINOR.PATCH:
- PATCH (2.3.0 → 2.3.1): bug fixes only, no expected change in behaviour.
- MINOR (2.3.1 → 2.4.0): new features compatible with previous use.
- MAJOR (2.4.0 → 3.0.0): incompatible changes, which may require action from whoever updates.
The value of this convention is that the number itself communicates the risk. Anyone who sees a component go from 2.x to 3.0 knows they must read carefully before updating. The same principle can also be applied to document templates and internal procedures.
How to write a good entry
A useful entry answers «what changes for me?». Some comparisons:
| Avoid | Better |
|---|---|
| Fix export bug | Fixed: PDF export no longer freezes on documents over 200 pages. |
| Updated dependencies | Security: updated the encryption library to fix a known vulnerability. |
| Settings refactor | Changed: settings are now grouped into three tabs; no values were lost. |
| Removed old format | Removed: import from the .xls format. Convert files to .xlsx before updating. |
Practical rules:
- start with the observable behaviour, not the technical detail;
- always state the actions required of whoever updates, especially in major versions;
- announce removals at least one version in advance, in the «Deprecated» category;
- one change per entry, one sentence per change.
Release notes for non-technical readers
Release notes start from the changelog but select and explain. An effective structure:
- The main news in two or three points, each with its concrete benefit.
- What you need to do, if there is anything to do.
- Other improvements, briefly.
- Known issues, if any, with a workaround.
In my work I write the changelog entry at the same moment I make the change: reconstructing it at the end of the month is slow and something always gets forgotten.
In short
- The changelog is the complete record of changes; release notes communicate the essentials to users.
- Do not copy the commit history: describe the effect for people who use the product.
- The Added, Changed, Deprecated, Removed, Fixed and Security categories make the record readable.
- Semantic versioning communicates the risk of an update through the number itself.
- Every entry says what changes and which actions are required.
