How to Keep a Changelog Your Users Will Actually Read

A git log is a record for machines. A changelog is a record for humans — it answers "what changed for me in this release?" The widely-adopted Keep a Changelog format makes that easy to write and scan.

The six categories

Group each release's changes under these standard headings, in this order:

• Added — new features.
• Changed — changes to existing behavior.
• Deprecated — features that will be removed soon.
• Removed — features removed in this release.
• Fixed — bug fixes.
• Security — vulnerabilities addressed.

Only include the categories that have entries. A bugfix release might just have Fixed.

How it maps to semantic versioning

The categories hint at the version bump:

• Removed or breaking Changed → a major bump (2.0.0).
• Added or Deprecated → a minor bump (1.3.0).
• Fixed and Security only → a patch bump (1.2.4).

What to leave out

• Internal refactors users can't observe.
• Every commit — summarize, don't transcribe.
• Vague entries like "various fixes." Say what you fixed.

Write entries from the user's perspective ("Fixed a crash when saving an empty form"), not the code's ("Null-check in save()").

Generate a clean entry

The CHANGELOG Generator turns grouped notes into a properly formatted Keep a Changelog section — canonical heading order, normalized bullets, empty categories skipped. Pair it with the Git Commit Builder to keep the messages those entries come from consistent too.