Changes files and CPAN::Changes::Spec

As I have mentioned on previous occasions in this blog, quests on Questhub can boost your productivity if you are into gamification. Another positive thing with doing quests on Questhub is that you actually learn something new.

So when I took the quest “Get 20 of my CPAN distributions to conform with the CPAN::Changes::Spec” it actually served several purposes.

  1. It raised the quality of 20 of my CPAN distributions by getting all my Changes files to adhere to a specified standard by using a uniform format
  2. I had fun
  3. I got to know a new module CPAN::Changes
  4. And I had fun

But it should not be a secret that this blog post also serves another more sinister purpose since I am currently on a new quest: “Blog about a module you are using”, but I would also like to reflect on the new stuff I learned and the new module I added to toolbox of modules I often use, namely CPAN::Changes.

Some time ago I collected my thoughts on communicating changes in my Wiki (the page has not been updated with the new stuff I learned, but it will be at some point).

In the page I describe my idea of the formatting of a Changes file and the idea of reverse chronological order. The formatting should contain bullet points on the single changes, the heading should be version number and date. And the reverse chronological order would serve for easier reading so you would always have the newest entry at the top (so you would save time to scroll down to the bottom).

In my opinion Changes communication and Changes files are very important, I very often consult Changes files for CPAN distributions and other packages of software when I want to see if and when a bug was fixed or a feature was introduced.

I was very happy to see that my view on Changes files formatting was very much in line with the CPAN::Changes::spec (part of CPAN::Changes) so the quest was not a tough one, but it required some work to get all of my distributions cleaned up, since the specification did formulate some more strict requirements.

So I picked up some new things:

  1. Dates should be uniform, the specification requires W3CDTF
  2. Keeping a uniform format means you can actually assert how wellformed a Changes file is

This would bring me to yet another module in my ever growing toolbox: Test::CPAN::Changes and its boilerplate.

        use Test::More;
        eval ‘use Test::CPAN::Changes’;
        plan skip_all => ‘Test::CPAN::Changes required for this test’ if $@;
        changes_ok();

Most of my CPAN distributions now have uniform Changes files adhering to the recommended standard and automated tests asserting this. I was actually only just able to get to 20 as specified by the quest, since some of my distributions where not in a state where I could easily get them in the bulk, but that is a different story and perhaps even another quest.

I can honestly recommend CPAN::Changes and Test::CPAN::Changes by BRICAS

There is however one thing I miss, a single thing I mention this in my wiki page and perhaps it should be a patch to CPAN::Changes::spec and Test::CPAN::Changes. It is what I refer to as the impact pointer. Is it nothing special, but I think when I heard about the concept I thought it was a really good idea.

The concept was not called impact pointer and I do not remember the exact wording, but I coined the term for use in my wiki page. Since I cannot remember where I heard it and how it was worded I still feel I should mention that I think it was INGY who mentioned the importance of the Changes file clearly communicating whether an update would be recommended with a certain release of a distribution of whether you could sit it over.

For now I do not want to conflict with the specification, so I try to remember to mention the impact pointer as the first bullet point under a release in a Changes file and I try to always try to categorize my releases into one of 4 categories:

  • Initial releases, it would be nice to get somebody to use and evaluate the release, so impact indicator is not so beneficial, but one could communicate, state of release, like alpha/beta/experimental/developer etc. – some of this can be communicated in the version number, but human readable terms can be nice to the untrained eye
  • Maintenance releases, house-keeping release, stuff like adding boilerplate code for testing and asserting your Changes file, indicating often that an update is not necessary
  • Bug fix releases, can be serious so the impact indicator is important, often it indicates that an update is recommended, often based on the severity of the bugs addressed
  • Feature releases, often updates are not required, but it would be nice to get somebody to use and evaluate the release, like an initial release

So in addition to the recommendations to your toolbox I want to recommend adding clean and concise information on whether an update is required/recommended/unnecessary – this really can save your users a lot of time.

It felt good to complete the original quest and it does feel good to write this blog post and complete yet another quest, but so much other stuff seems to go on the TODO list, like creating a POC for the impact indicator for CPAN::Changes::spec, updating my wiki page and getting the rest of my CPAN distributions addressed so they also adhere with the recommended standard.

Advertisements
Changes files and CPAN::Changes::Spec

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s