All the Perl that's Practical to Extract and Report

Writing a Changes File

Ovid on 2009-09-29T14:52:06

Why do so many CPAN developers get their Changes files so wrong?

  • Please update the change log! An ignored change log doesn't tell me if I need to upgrade your module.
  • The change date is important, but not as important as the version number. The date in the Changes file has an excellent chance of not being the date in the version dropdown on CPAN, so we can't correlate the two. Put your version number in there.
  • Put your most recent changes at the top. When people click on changes, they usually want to see the most recent ones and scrolling down is annoying.
  • For each change set, put the most important changes at the top. If you have a long change set (shorter is better), it's easy to miss the "incompatible API change" buried halfway through.
  • If your bug fix has an RT number, please put it in there. Many times the ticket will have important information we don't want to lose.
  • If someone contributed a patch please list them in the changes file. Sometimes if an author doesn't have the time to respond, it's nice to talk to the person who's familiar with the code you're struggling with.
  • "Fixed regression" is not an appropriate change message because I need to know if the regression impacted me. "POD tweaks" is probably OK because it doesn't affect me.

Oh, wait it was a rhetorical question wasn't it?

cowens on 2009-09-29T15:26:16

Because change logs don't scratch an itch for the developer.

Re:Oh, wait it was a rhetorical question wasn't it

jrockway on 2009-09-29T16:21:49

Exactly. If you want a changelog, submit a patch that updates the changelog. To the original developer, this is something is forgotten in the rush to quickly release relevant features and bugfixes.

Anyway, I feel that you are entitled to a full refund on any module that doesn't include a changelog.

Re:Oh, wait it was a rhetorical question wasn't it

Ovid on 2009-09-29T16:47:55

Well, in that case, I shouldn't care about documentation, tests, or any other silly thing like that.

If the author is providing code and doesn't care enough to make it easy for people to consume, that's fine. It's their code and if they release free code, they can do as they will. It still doesn't make it any easier for the consumer and the consumer will (quite understandably) get frustrated when they see something they think might be useful but the author didn't care enough to make it useful. I've got plenty of better things to do with my spare time than reading through code which might or might not be useful to me. I'll just look for another solution. Of course, your mileage may vary :)

Re:Oh, wait it was a rhetorical question wasn't it

dug on 2009-09-30T00:23:56

But don't documentation and tests help the developer? If I write my documentation first, it makes me think about the API, and because I don't like writing documentation it makes me think about simplifying it. Which is good for my code.

If I write my tests next, it gives me a baseline of correctness. I get to try to write the simplest code possible to pass my tests. Which is good for my code.

I see your point about ease of consumption, and I certainly appreciate it when folks rock an awesome change log. Is there any motivating factor for the developer, other than extra cookies, that you can think of?

Cheers,

-- Douglas Hunter

Re:Oh, wait it was a rhetorical question wasn't it

Ovid on 2009-10-01T08:18:59

Is there any motivating factor for the developer, other than extra cookies, that you can think of?

How about "caring about your users"? :)

Re:Oh, wait it was a rhetorical question wasn't it

Alias on 2009-09-30T01:09:18

Yeah, god forbid we release code to other people for any reason other than as our personal installation dependency and backup system.

release automation

daxim on 2009-09-29T15:51:42

Using a release tool like ShipIt helps the author against simply forgetting to update the Changes file.

You forgot - the recommendation

jonasbn on 2009-09-30T20:44:43

A good idea is next to the version number is giving a recommendation on whether a user should update or not. If it is just a maintenance release addressing smoke test failures on "Titanix - the system they say wouldn't go down" - an upgrade might not be required. Other releases might require updates fixing serious bugs etc. See: http://cpansearch.perl.org/src/JONASBN/Business-DK-CPR-0.05/Changes for an example

Good piece btw - take care,

jonasbn