Image Description
Writing a changelog
A changelog answers a simple question: what changed?
Unfortunately, changelogs occasionally answer it with entries such as "fixed bugs". Technically true. Spectacularly unhelpful.
Write for humans
Describe changes in terms somebody maintaining or using the software can understand. You do not need to paste your entire Git history into the file.
Useful categories
Depending on the project, headings such as Added, Changed, Fixed, Deprecated, Removed and Security can make entries easier to scan.
Group changes by release
Give each released version a heading and, where useful, its release date. Keep an Unreleased section if you want somewhere to collect changes before the next version is published.
Do not rewrite history casually
Once a changelog describes a published release, treat it as a record. You can correct mistakes, but avoid silently turning old release notes into something that no longer reflects what was actually released.
Changelog or release notes?
A changelog is the ongoing technical record. Release notes can be a friendlier summary aimed at users. They overlap, but they do not have to be identical.
Write for the person upgrading
A changelog is not your Git history with nicer punctuation.
"Changed variable name in parser" may be fascinating to you at 2 in the morning, but a user probably wants to know that importing a particular file no longer crashes.
Describe the effect of the change where possible.
Group related changes
Headings such as Added, Changed, Fixed, Deprecated, Removed and Security can make a longer release much easier to scan.
You do not have to use all of them. An empty "Deprecated" heading sitting there looking lonely does not help anybody.
Do I include every tiny change?
Usually, no. Include changes somebody using or depending on the software may care about. Internal refactoring with no user-visible effect can often stay in your commit history.
An example
## 1.4.1 ### Fixed - Fixed a crash when opening an empty playlist. - Screen readers now announce the state of the Shuffle checkbox. ### Changed - Improved the error shown when an audio file cannot be opened.
That tells me considerably more than "various bug fixes".
Further reading and external resources
Want to dig into this a bit more? These are good places to go next. If anything here ever disagrees with the official documentation, trust the official documentation.
Previous: Preparing your first software release | Next: Writing useful release notes