Keep a Changelog: The Complete Guide
Keep a Changelog is a widely adopted standard for formatting changelogs in open-source and commercial software. It defines clear categories — Added, Changed, Deprecated, Removed, Fixed, Security — and a consistent format that both humans and tools can parse. For a look at how AI can handle this categorization automatically, see our post on <a href='/blog/ai-changelog-generation-from-commits'>AI changelog generation from commits</a>. Whether you follow the standard strictly or adapt it, understanding the principles behind it will make your changelogs dramatically more useful.
Key Points
The standard categories
Keep a Changelog defines six categories: Added (new features), Changed (existing functionality changes), Deprecated (soon-to-be-removed features), Removed (removed features), Fixed (bug fixes), and Security (vulnerability patches). Using these consistently helps readers find what they need.
Version and date every entry
Each changelog entry should be tied to a version number (following Semantic Versioning) and a release date. This creates a clear timeline and makes it easy to correlate changelog entries with deployed versions.
Write for humans, not machines
The standard explicitly states that changelogs are for humans, not machines. Dumping git log output into a CHANGELOG.md file violates the spirit of the standard. Every entry should be readable by someone who did not write the code.
Automate the format, curate the content
PatchNotes follows Keep a Changelog conventions automatically — proper categorization, version headers, dates. The AI generates human-readable descriptions from your commits, giving you the best of both worlds: automation with curation.
Why PatchNotes?
- AI-generated — transforms your commits into user-friendly release notes automatically.
- GitHub-native — connects to your repo and generates changelogs on push or release.
- Publish anywhere — hosted changelog page plus an embeddable widget for your app.
Ready to automate your changelog?
Everything you need to know about maintaining a changelog. Standards, tools, and automation.
Get Started Free