What is a changelog?
A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.
Why keep a changelog?
To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.
Who needs a changelog?
People do. Whether consumers or developers, the end users of software are human beings who care about what’s in the software. When the software changes, people want to know why and how.
from Keep a Changelog
Keep a CHANGELOG with Olivier Lacan (Changelog Interviews #127)
Make it easy to compile a new changelog
- Every PR should add newest changes under UNRELEASED heading at the top of the file
- When creating a new release, you can then move everything from UNRELEASED to newest version
How to not write a good changelog
I recently came across this iOS app changelog for an app that I’ve been using.
Every entry is just “Bug fixes and performance improvements”. That tells me absolutely nothing and at this point, I don’t believe they keep finding performance improvements every time like this.
If you fixed bugs, please let the user know which ones. It’s great to know if a bug that was a deal-breaker for you gets fixed and you can go back to using an app/product/service.
If you add features or improve existing ones, please let the user know what they are. You’re leaving an opportunity to educate or advertise to your users what new things your app does on the table when you don’t.
