How to keep a CHANGELOG — step by step, so humans actually read it

The Keep a Changelog standard opens with a line that saves a lot of time: changelogs are for humans, not machines.
Which leads to an uncomfortable conclusion. If your answer to "what's new?" is a link to the commit history, you don't have a changelog. That history is merge commits, "fix typo," README edits and twenty lines that tell a user nothing. The standard calls this an anti-pattern in as many words.
Good news: a decent changelog takes ten minutes to set up. Here's how.
1. Create the file at the root
The name is exactly this: CHANGELOG.md. Not changes.txt, not a wiki page. GitHub and GitLab surface this file next to the README, and that's where people look.
2. Add an "Unreleased" section — this is the real trick
Right under the title, make a section for unreleased work:
# Changelog
## [Unreleased]
### Added
- Export notes to PDF
### Fixed
- The "Sign in" button didn't work in Safari on iPhone
The point is that you write here today, the moment you finish something — not on release day.
Trying to recall three weeks of changes right before shipping is exactly where the legendary "minor fixes and improvements" comes from. You're not lazy; you genuinely don't remember.
3. Sort into the six types
The standard has exactly six, and they cover everything:
- Added — new features.
- Changed — behaviour of something existing changed.
- Deprecated — still works, going away soon.
- Removed — gone now.
- Fixed — a bug fix.
- Security — a vulnerability closed.
The most-ignored one is Deprecated, and the standard warns about it explicitly. Yet it's the only place you can warn people before something breaks. Removing a feature with no notice is a nasty surprise; removing it two versions after you flagged it is just normal work.
4. Dates in ISO only, newest on top
A version heading looks like this:
## [1.2.0] — 2026-08-26
YYYY-MM-DD isn't fussiness. 05.08.2026 reads as two different dates depending on the country — precisely the small thing that makes people mix up which version is newer.
Order: newest first. People open the file to learn what changed for them now, not in 2024.
5. Tie it to version numbers
The number in the heading isn't arbitrary. It follows semantic versioning: break compatibility and it's a major, add a feature and it's a minor, fix a bug and it's a patch.
That makes the changelog twice as useful: the number tells people whether to brace for pain on upgrade, and the section beneath it tells them exactly which pain.
6. Make it write itself, almost
If you format commits with Conventional Commits, the draft generates itself. The format is simple:
feat(auth): add email sign-in
fix: stop crashing on an empty payment response
Per the spec, fix maps to a PATCH release, feat to a MINOR one, and an exclamation mark before the colon (feat!:) or a BREAKING CHANGE: footer to a MAJOR. Tools like git-cliff, release-please or changesets read that markup and assemble a draft file.
The key word is draft. You then read it and rewrite it in human terms: not "fix: null check in parser," but "no longer crashes when you upload a file without a header." If the commit format itself is the hard part, start with commit messages — the changelog comes almost free after that.
7. Throw out what the reader doesn't need
Doesn't belong in a changelog:
- refactoring nobody outside will notice;
- test tweaks, CI changes, typos in comments;
- "updated dependencies" — unless it fixes a vulnerability, in which case it's
Security.
One test: if the change makes no difference to someone using the project, it doesn't go in the file. A changelog is a curated list of notable things, not a dump of everything.
What you get
A file you can scroll once, where the top shows the latest version, its date, and three or four items in plain language. Six months from now you'll open it yourself to remember when you broke compatibility — and find the answer in ten seconds instead of half an hour in git history.
Keep one thing separate: what a user reads in an app store or on a release page is a different genre. What changes between them, and what to write in each, is in the changelog vs release notes comparison.
Do I need a changelog on a solo project?
Yes, and it pays off faster than on a team. "You" in six months is a stranger with no context. The question "which version did I change the storage format in?" surfaces exactly when something has broken, and you need the answer in a minute.
Can I just ask AI to build the changelog from commits?
You can, and the draft is decent — especially with tidy commits. But the model doesn't know what's user-visible: it will summarise a new feature and a variable rename with equal diligence. Ask it to group by the six types and drop internal work, then do the final cut yourself.
What if the project has gone a year with no changelog?
Don't reconstruct history — you'll lose a week and still get it wrong. Start the file today, add a line like "earlier versions weren't documented," and begin from the current version. Three releases later nobody will care about the gap.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





