Changes and CPAN, CPAN::Changes and my Changes

Following up on the comments to my blog post on CPAN::Changes and CPAN::Changes::Spec, I created a fork of the distribution on Github and implemented a first shot for the author to evaluate. I sent the pull request yesterday, so now it will be interesting see whether it will be found useful at all.

I did a lot of thinking before starting the actual coding and I was not quite satisfied with the vocabulary I was using to describe the concept. Originally I referred to the concept as impact pointer, but it is simply misleading and not particularly descriptive. So when it occurred to me that the concept was actually hints on how the reader should view the changes and release described it came to me that the obvious name should be “update hint”.

Hints are everywhere and is the term is highly popular these days. Hints are less intrusive and in this case a much better description.

Here is an example lifted from the POD.

0.03 2010−08−01 − update recommended

− Fixed serious bug in bar method

0.02 2009−07−17 − update not required

− Added more foo() tests

0.01 2009−07−16

− Initial release

I decided for two values of the hint:

        - update recommended
        - update not required

The first for for releases, which address serious issues/bugs like security fixes, memory leaks etc. the second for releases which are housekeeping releases, updates to tests, documentation, build scripts etc.

As you can see there is no hint for the initial release. I do not want to impose my proposal on the existing specification as such and I well let it be up to the maintainer to decide whether it should be optional and what the actual values should be, my proposal works, but it just a proof of concept and in my opinion it is a nice concept I hope will be adopted.

Please feel free to evaluate my proposal for update hints in the CPAN::Changes::Spec and let me know what you think.

jonasbn, Copenhagen/Denmark

Changes and CPAN, CPAN::Changes and my Changes

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 $@;

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.

Changes files and CPAN::Changes::Spec