What is a changelog? Definition, purpose and examples
A changelog is a dated list of the changes in each version of a piece of software, kept in order with the newest release first. It lets anyone who uses the project see what is new, what was fixed and what might break, without reading the source code or the git history.
That short definition hides a few choices: who the list is for, how much detail it holds and where it lives. This guide covers what a changelog contains, what it is for, the forms it takes and how to start one.
What a changelog contains
Every entry in a changelog answers the same question: what is different in this version? A useful changelog usually has:
- One section per release, with the version number and the release date.
- The changes of that release, grouped by type, such as Added, Changed, Deprecated, Removed, Fixed and Security.
- An Unreleased section at the top for changes that are merged but not shipped yet.
- Links to the pull request, issue or comparison for readers who want the detail.
The Keep a Changelog convention describes this layout in full and is the most common one for files kept in a repository. A small entry looks like this:
## [1.4.0] - 2026-11-12
### Added
- Export a report to PDF from the toolbar.
### Fixed
- Signing in no longer loops back to the login page.What a changelog is for
A changelog does a few jobs at once:
- It saves readers time. Someone deciding whether to upgrade can scan one list instead of reading every commit.
- It warns about breaking changes. A removed option or a changed default belongs in the log where an upgrader will see it.
- It keeps a record. When a bug appears, the changelog shows which release introduced a change, which narrows the search.
- It shows the project is alive. Regular entries tell users that someone is maintaining the software.
Where a changelog lives
The same list can be published in more than one place:
- A CHANGELOG.md file in the repository root. It is versioned with the code and is the usual choice for libraries and tools.
- A public changelog page on your website, for products whose users do not read repositories.
- An in-app "What's new" notice that shows the latest release inside the product.
- GitHub Releases, where each release carries its own notes next to the downloadable code.
A changelog is not a commit log
It is tempting to paste the output of git log into a file and call it a changelog. Commit messages are written for maintainers, in the moment, and they include refactors, dependency bumps and typo fixes that no reader needs. A changelog is edited: someone chooses what matters and says it in plain language. The guide on how to write a changelog goes through the habits that make one worth reading.
Changelog or release notes?
The two terms overlap. A changelog is the complete, dated record, usually for developers. Release notes explain one release to the people who use the product. Many teams write both from the same list of changes; the comparison of changelog and release notes shows one change written both ways.
How to start one today
- Create a CHANGELOG.md with a short header and an empty Unreleased section. The Keep a Changelog template is a ready starting point.
- Add a line for each notable change as you merge it, instead of reconstructing the list at release time.
- At release time, rename Unreleased to the new version and date, and open a fresh Unreleased section.
- Decide who reads it. If your users are not developers, publish a shorter version for them as well.
If keeping the list up to date is what stops you, ReleaseTale drafts both versions from the commits of a release, and you edit them before publishing. You can see what the output looks like on the changelog examples page.
Frequently asked questions
What is a changelog?
A changelog is a dated list of the changes in each version of a piece of software, with the newest release first. It tells users what is new, what was fixed and what might break.
What is the purpose of a changelog?
It saves readers the time of reading commits, warns them about breaking changes, keeps a record of when each change shipped and shows that the project is maintained.
Where should I keep a changelog?
Most projects keep a CHANGELOG.md in the repository root. Products often also publish a public changelog page, an in-app What's new notice or GitHub Releases.
Is a changelog the same as a git log?
No. A git log lists every commit and is written for maintainers. A changelog is edited: it keeps only the changes that matter to readers and describes them in plain language.