A change log is the quickest, most convenient way for users and contributors to identify significant changes in a project as it moves from one version to the next. The log exists to keep users informed.
Unfortunately, many open source project leaders have little motivation to provide a meaningful CHANGELOG file and are purely focused on shipping the code. Instead of writing clear, understandable logs for a release, many developers resort to dumping git logs, which are often rife with messy commit messages, into the CHANGELOG file.
Olivier Lacan, software engineer at Code School, has created a site and corresponding GitHub repository called Keep a CHANGELOG, with an extensive collection of recommendations for writing better change logs.
The project page offers a variety of tips for improving change logs, i.e. how to list releases, recommended date format, sections and labels for classifying changes, and file naming convention.
One helpful tip Lacan offers, which isn’t commonly seen among even the finest, hand-crafted CHANGELOGs, is the recommendation for keeping an “Unreleased” section at the top. This helps users track for potential changes in progress for upcoming releases. Maintaining an “Unreleased” section minimizes the effort of writing the logs at release time, as you can easily add the version number to the section as changes are added and create a new Unreleased header.
Software Tools Are for People
Lacan makes a strong case for prioritizing the creation of a changelog for your open source project:
Why should I care? Because software tools are for people. If you don’t care, why are you contributing to open source?
He hopes that the Keep a CHANGELOG project will help to shape a better CHANGELOG file convention for all open source projects. Discussions and suggestions are welcome in the issues queue of the project’s GitHub repository. Contributors have already logged more than two dozen considerations.
WordPress.org offers some basic tips for improving change logs, but the official plugin directory doesn’t require developers to maintain a CHANGELOG file. Lacan’s Keep a CHANGELOG project is a complementary resource that can help WordPress developers and all open source project managers to write better logs for users and contributors.
It’s worth mentioning that while we do have changelogs supported in the readme.txt file for the plugins directory, there is a size limitation on that file. So, very rarely, changelogs kept there will exceed our limits. In such a case, I recommend to people to make changelog.txt files, or just CHANGELOG files and copy older entries into there as needed.
Knowing what changed is important, and the readme entries are meant to be a sort of higher level view, readable by users and sent as part of the update process. So, keep them simple, make them understandable, and there’s no need to detail exact code changes made. High level overview, sort of thing, works best.