How to write a good changelog
December 21, 2009
I’ve just read through the Python 3.1 changelog, and it has encouraged me to write up something that I’ve wanted to say for a while, but never quite got round to: dear open source developer, please write good changelogs for your project.
What do I mean by changelogs? Historically, the term has meant something akin to “Our version control system sucks, we need to keep track of logical changes by hand”. This leads to a “changelog” that looks something like this:
1999-03-24 Stan Shebs address@removed
* configure.host (mips-dec-mach3*): Use mipsm3, not mach3.
Attempt to sort out SCO-related configs.
* configure.host (i[3456]86-*-sysv4.2*): Use this instead of
i[3456]86-*-sysv4.2MP and i[3456]86-*-sysv4.2uw2*.
(i[3456]86-*-sysv5*): Recognize this.
* configure.tgt (i[3456]86-*-sco3.2v5*, i[3456]86-*-sco3.2v4*):
Recognize these.
If you’re like any developer not involved with the project, that changelog entry is a complete parse error. You have no idea what the actual change is, whether you should care, whether the change was cosmetic or semantic… A compiler analogy would be that if the version control logs are machine code, this is a barely decorated disassembly.
Humans generally don’t want to read a disassembly of version control logs. They want to know what changed at a higher, human level, units of change that can be grokked in terms of new tools available to them, new syntax, new libraries, what they need to change in their data to ensure compatibility…
A good changelog doesn’t just disassemble version control logs. It presents an executive summary of a whole slew of changes, in terms that make it clear why I, the end user, should be giving a damn.
Thanks for your attention.