Every software release should come with a list of changes that are present in that release. What goes in this list depends on your audience. Let’s consider a changes file for a module released on CPAN.
For a CPAN module, the audience is other developers. Some of the readers have used this module before, and want to know what’s new. Other readers haven’t used this module, and want to know if the changes in this release will change their minds.
Before we get to the how-to, let’s take a particularly poor example, the Changes file from the Dancer project.
(Note: I’ve got nothing against Dancer, and the devs I’ve talked to in the project all seem to be nice people, but their changes file really is egregiously bad.)
First problem, no release dates. Release dates are really important. They help people see what the development velocity for the project is. There is no excuse for not putting them in your changes file.
(And remember, it’s a release date, not a release timestamp. No one cares that you released the module at 07:23:52 GMT.)
However, there is an even bigger problem, which is that the organization of the changes file is completely and utterly arbitrary. They’ve listed changes by author. This is meaningless to readers.
(I’m all for crediting each contributor, but that should go at the end of each individual change description.)
The changes in a changes file should be grouped in some way that helps readers understand the nature of each change. Ideally, the most important stuff comes first, and least important comes last.
The Dancer changes file has as its second change “turned a tab into the right number of spaces”. Who cares? Does this affect anyone using the code? No.
Overall, the Dancer file has a number of changes listed which no one will care about, like fixing typos in pod. There’s no reason to mention this sort of thing unless the typo in question was a factual error or broken code. If it was just a spelling error, no one really cares.
So there’s no release dates, no useful ordering of changes, and some of the changes are completely unimportant, obscuring the useful information. I give this changes file an F.
For an example of a good changes file, look at Moose.
We separate changes into broad categories that help our readers. The categories are “API CHANGES”, “NEW FEATURES”, “ENHANCEMENTS”, “BUG FIXES”, and occasionally “OTHER”. These categories are always presented in that order.
The most imporant part of the ordering is that API changes (anything which breaks backwards compatibility) are always listed first. The order of the next three is debatable, but that matters less. What’s important is that we break them down into useful categories. If you’re a Moose user who’s been waiting for a specific bug fix, it’s easy to figure out whether the new release fixes that bug.
Prior to 0.93_01, Moose’s changes file wasn’t so great. Changes were listed by the package they affected, which is pretty useless. Moose has a lot of modules, and most of them aren’t exposed to the end user. Knowing that a bug was fixed in
Moose::Meta::Role::Application::ToRole doesn’t really help anyone.
If you’re a CPAN author, please think of your intended audience when you write your Changes file. Put the most important stuff first. If you want to break the file down into sections, do that based on something the reader cares about. And don’t forget your release dates!