What is a changelog?
A changelog is a file that records all notable changes to a project, organized by version and date. It lives in the root of your repository as CHANGELOG.md and is one of the first files developers look for when evaluating or adopting a library.
A good changelog answers three questions for any given version: What's new? What broke? What do I need to change?
The Keep a Changelog format
Keep a Changelog is the de facto standard, used by thousands of open source projects. It defines a consistent structure that developers recognize immediately:
The six change categories
Keep a Changelog defines six categories. Use only the ones that apply to each release:
- Added — new features
- Changed — changes to existing functionality
- Deprecated — features marked for removal in a future version
- Removed — features removed in this version
- Fixed — bug fixes
- Security — security fixes (always call these out separately)
What to include and what to skip
| Include | Skip |
|---|---|
| New user-facing features | Internal refactors with no behaviour change |
| Bug fixes that affected users | Test-only changes |
| Breaking changes — always | CI/build changes (unless they affect consumers) |
| Performance improvements (with numbers) | Dependency version bumps (unless they affect the public API) |
| Security fixes | Typo fixes in code or comments |
| Deprecations | WIP or stale commits that didn't ship |
Breaking changes: how to communicate them
Breaking changes deserve special treatment. They're not just another list item — they're the reason a user's CI might fail after updating. Communicate them:
- In a dedicated
### Breakingsection at the top of the release - With a clear description of what changed and what the migration path is
- With a link to a migration guide if the change is complex
- In the version bump — breaking changes mean a MAJOR version increment in SemVer
The [Unreleased] section
Keep a Changelog recommends maintaining an [Unreleased] section at the top of the file. As you merge features and fixes, add them here. When you release, rename the section to the version number and date, and create a new empty [Unreleased]. This keeps the changelog always up to date and makes release day trivial.
Changelog vs CHANGELOG.md vs release notes
These terms get conflated. To be precise: CHANGELOG.md is the file in your repository — the technical record. A changelog page (like a hosted public changelog at yourapp.com/changelog) is the user-facing version. Release notes are what you publish with each release on the App Store, GitHub, or via email. They're all related but serve different audiences. See our full comparison.
Never delete old entries. A changelog is a historical record. Deleting old versions removes useful context for users on older versions. If something was wrong in an old entry, add a correction note — don't delete.
How to generate a changelog automatically
Maintaining a changelog manually is the main reason teams let it go stale. ChangelogAI generates the Keep a Changelog format from your commits — paste your git log, get a properly formatted CHANGELOG.md entry in seconds. Copy and prepend to your existing file.
Frequently Asked Questions
Should I use CHANGELOG.md or changelog.md?
CHANGELOG.md (all caps) is the convention used by most open source projects. Some tools (like GitHub) look for it specifically. Use all caps.
How do I handle a project with no changelog?
Start now. Create a CHANGELOG.md with the current version, date, and the most important changes. You don't need to retroactively document every past version — just start from today and go forward.
What's the difference between a changelog and release notes?
A changelog is the persistent historical record in your repository. Release notes are the per-release communication you publish to users. See our full guide: /changelog-vs-release-notes/
Should I include every commit in the changelog?
No. Only user-facing changes belong in the changelog. Skip internal refactors, test changes, CI updates, and dependency bumps unless they affect users.
How do I automate changelog generation?
Paste your git log into ChangelogAI and select the Keep a Changelog format. You get a properly formatted entry in seconds to prepend to your CHANGELOG.md. API access for full automation is on the roadmap.
Related Tools & Guides
Stop writing release notes by hand
Paste your commits. Get polished, publish-ready release notes in seconds. Completely free, no account needed.
Try ChangelogAI Free →