A usable changelog has one entry per version, the newest first, an ISO 8601 date on each, changes grouped by type, and a clear marker for anything that breaks. The Keep a Changelog convention says it plainly: changelogs are for humans, not machines. Clear structure then helps machines too.
The structure that works
Keep a Changelog sets out guiding principles that still hold:
- Every version gets its own entry.
- Similar types of changes are grouped together.
- Versions and sections can be linked directly.
- The newest version appears first.
- Each version shows its release date.
- The file says whether the project follows Semantic Versioning.
The change types it names are Added, Changed, Deprecated, Removed, Fixed and Security.
A small example
# Changelog
## [Unreleased]
## [1.4.0] - 2026-10-01
### Added
- New `--format json` option for scan output.
### Deprecated
- The `--legacy-output` flag. It will be removed in 2.0.
### Security
- Updated a bundled parser to a release that fixes a denial of service issue.
Rules that save readers time
Keep an Unreleased section at the top, and move its entries into a versioned section at release. List deprecations, removals and breaking changes so people see what will break before they upgrade. Use YYYY-MM-DD dates, which avoid regional confusion.
Do not paste raw commit logs. Keep a Changelog points out that commit logs carry noise such as merge commits and vague titles. Write entries that describe what a user will notice.
Be consistent. A partial changelog misleads people into thinking it is complete. Mark yanked releases with a YANKED tag, and revise past entries when they turn out to be wrong.
Why this suits retrieval
Questions like "what changed in 1.4.0" or "when was the flag removed" are answered by a heading, a date and a bullet. Stable heading anchors let a link land on the right release. Plain dates let a person or a tool order events without guessing.
Dates should be true. Google's guidance on dates says they should describe when the page was published or updated, and that visible and structured dates should match. See honest publish and updated dates.
Security entries
State the fix and the affected versions in plain words, and link to the advisory if one exists. Do not describe exploit steps. If your product ships fix pull requests, say which release carried which change.
Quick check
Should the changelog be a single page or one page per release?
Either works. Keep a Changelog uses one file with a section per version. Very long histories may be easier to browse split by year, with the same structure.
Is generating it from commits acceptable?
As a draft, yes. Publish an edited version, because raw commit messages are noisy.
Sources
Last reviewed: 19 October 2026.
