Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Ovid (2709)

Ovid
  (email not shown publicly)
http://publius-ovidius.livejournal.com/
AOL IM: ovidperl (Add Buddy, Send Message)

Stuff with the Perl Foundation. A couple of patches in the Perl core. A few CPAN modules. That about sums it up.

Journal of Ovid (2709)

Tuesday September 29, 2009
09:52 AM

Writing a Changes File

[ #39693 ]

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.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Because change logs don't scratch an itch for the developer.

    • 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.

      • 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 pl

        • 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. I

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

            How about "caring about your users"? :)

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

  • Using a release tool like ShipIt [cpan.org] helps the author against simply forgetting to update the Changes file.
  • 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 [perl.org] for an example

    Good piece btw - take care,

    jonasbn