Changes files and CPAN::Changes::Spec

In: Articles

22 Jan 2014

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.

8 Responses to Changes files and CPAN::Changes::Spec

Avatar

Neil Bowers

January 22nd, 2014 at 18:20

Good point on the “impact pointer” – you should email BRICAS and suggest incorporating it in some way. This can safely go after the date for the moment, and I think that’s the right place for this information to go anyway.

0.02 2014-01-20 housekeeping

Avatar

jonasbn

January 23rd, 2014 at 13:08

Darn I forgot to mention the marvelous service for testing your Changes file

http://changes.cpanhq.org/

An example could be my account:

http://changes.cpanhq.org/author/JONASBN

if you are a CPAN contributor you should be able to find yourself or you can use the online validator:

http://changes.cpanhq.org/validate

jonasbn

Avatar

Gabor Szabo

January 26th, 2014 at 04:59

What might be interesting is to see how, besides blogging about it, could the state of Changes files further improved with “impact pointers”?

This is probably cannot be automated, so I wonder, would it be too much to ask you to offer peer-review of the Changes files?

Avatar

jonasbn

January 26th, 2014 at 05:27

Hi Gabor,

I actually believe it can be asserted just as the date and hence automated.

The hard part is agreeing on acceptable values (enumerations). Whether a release is a bug fix release, feature release, housekeeping, developer release or experiment, beta, alpha or whatever, the impact pointer should be boiled down by the author to one of two.

- update recommended/required
- update not required/necessary

I am unsure on the actual wording, since it is only a pointer I would like it to be guiding and therefor use the word indicating a recommendation. And for the opposite situation I prefer required, but using the same words do communicate badly.

- update not recommended would be bad, but perhaps a value we should allow? – I cannot imagine all scenarios, but I would prefer it to be simple.

jonasbn

Avatar

jonasbn

January 26th, 2014 at 05:34

Hi Neil,

CPAN::Changes is on Github

https://github.com/bricas/cpan-changes

So I am currently looking into creating a patch/pull-request.

https://github.com/jonasbn/cpan-changes

jonasbn

Avatar

ether (Karen Etheridge)

January 29th, 2014 at 15:04

While it can be a good idea to check your Changes syntax with a unit test, I implore you to not add this to the main test suite for your distribution (i.e. a test that is run for every user on every installation). Consider what can happen if the CPAN::Changes::Spec changes and you haven’t adjusted your Changes file yet — the test will fail, which will prevent your distribution from installing!!!

Instead, keep the test in xt/release/cpan-changes.t, so it is only run for you, the author.

And, at that point, you can change the code so as to *require* the installation of the syntax checker, rather than skipping the test if it’s not installed:

use Test::More;
use Test::Requires ‘Test::CPAN::Changes’;
changes_ok();
done_testing;

And one more thing – you can achieve all this automatically if you use
Dist::Zilla, by including this in your dist.ini:

[Test::CPAN::Changes]

Avatar

jonasbn

March 1st, 2014 at 07:41

I have created a fork of the distribution on Github and have implemented a proof of concept, you can read more at:

http://logiclab.org/wordpress/2014/03/01/changes-and-cpan-cpanchanges-and-my-changes/

Avatar

Dereferenced.com » Blog Archive » Some Modules I’m Looking At Currently

March 16th, 2014 at 18:40

[...] learned of this module from this blog post, and am both intrigued and frustrated. Intrigued, because I’ve always felt that changes-files [...]

Comment Form

About this blog

This blog acts as a channel for communicating logicLAB’s open source activities. Announcements on open source initiatives, involvements and releases of open source distributions of software products, projects and applications.

Photostream

  • jonasbn: Book wrote a more elaborate piece on CPAN deletions, which is worth mentioning: http://blogs.perl [...]
  • Neil Bowers: It would be good to hear your thoughts on supporting both an OO and procedural interface: what was t [...]
  • J: I'm experiencing the same issue as Petar. Anytime I click on any file, ‘No violations found’. N [...]
  • Petar: Nevermind that, I solved it with: perlcritic --brutal --verbose 5 lib t > perlcritic.txt || EX [...]
  • Petar: Hi Jonas, I tried adding perlcritic command as Windows batch command, but since my code has viola [...]

Calendar

January 2014
M T W T F S S
« Nov   Feb »
 12345
6789101112
13141516171819
20212223242526
2728293031