Changelogs and release notes
Tell your users what changed, in language they care about.
- Distinguish a changelog from raw commit history
- Group changes by type and call out breaking changes
- Connect versions to changes with semantic versioning
A changelog is a human-readable summary of what changed in each release, written for the people who use your software. It's the last layer of the documentation stack — and the one your users actually read.
A changelog is not your git log
Your commit history is for developers and is full of detail ("Fix off-by-one in pagination"). A changelog is for users and is curated: it answers "what's new, what's fixed, and what might break me?" Group entries by type so a reader can scan for what matters to them:
## [1.4.0] - 2026-06-08
### Added
- Export to CSV from the reports page.
### Fixed
- Last page of results no longer shows up empty.
### Changed
- Search is now case-insensitive by default.This grouped style (the widely-used "Keep a Changelog" format) lets users jump straight to the section they care about.
Flag breaking changes loudly
The single most important entry is anything that breaks existing usage — a renamed option, a removed feature, a changed default. Surface these prominently (a Breaking section or a clear marker). A user upgrading needs to know what will stop working before it bites them.
Versions that signal meaning
Pair the changelog with semantic versioning — MAJOR.MINOR.PATCH:
- PATCH (1.4.0 → 1.4.1): backwards-compatible bug fixes.
- MINOR (1.4.0 → 1.5.0): new features, still backwards-compatible.
- MAJOR (1.4.0 → 2.0.0): breaking changes.
The version number itself becomes documentation: a jump to 2.0.0 warns users to
read the changelog carefully before upgrading.
Write changelog entries as you merge changes, not in a panic at release time.
A one-line note while the change is fresh is accurate; a reconstruction from
git log weeks later is a chore that misses things.
Where to go next
That completes the Documentation that lasts module — READMEs, docstrings, commit messages, ADRs, and changelogs cover documentation from the inside of a function out to your end users. Next up in the curriculum: deepening the Python and JavaScript/TS language tracks.