How to become a CPAN contributor - part 2

Aug 1, 2018 by Mohammad Sajid Anwar

In the previous article I described some typical issues that are good for first time CPAN contributors to tackle. In this article, I will go through the nitty-gritty of fixing issues, and some gotchas to watch out for. If you’re not familiar with the differences between a Perl distribution, module and package, check out this guide.

Missing license meta name

This is where the build script is missing a license name. It should be an easy fix - just add the license name to the build script. However there is a catch and I have been bitten by it before: the license meta name depends on the build script type. For example, if the distribution document says the license is “Artistic 2” in Makefile.PL the meta name would be “artistic_2” whereas in a dist.ini it would be “Artistic_2_0”.

E.g. the Makefile.PL from my distribution Map::Tube

...
ABSTRACT_FROM => 'lib/Map/Tube.pm',
LICENSE       => 'artistic_2',
EXE_FILES     => [ 'script/map-data-converter' ],
...

Compared to the dist.ini from my distribution Map::Tube::Delhi

...
author  = Mohammad S Anwar <mohammad.anwar@yahoo.com>
license = Artistic_2_0
copyright_holder = Mohammad S Anwar
...

If you are adding a software license to a distribution, Software::License is a good resource which has many different types of Open Source licenses.

One thing to check for is whether the distribution repository has a META.yml file or not. If it does, adding the license meta name to the build script may cause the build process to warn: “Invalid LICENSE value …”. This happens because the META.yml already contains a license value of “unknown”, which conflicts with the build script. The solution here is to delete the META.yml file and build the distribution, adding the newly-generated META.yml back into the repository.

You might be thinking, why would you keep META.yml in the project repository as it can be easily generated? I agree it’s probably a mistake, but keep in mind your intent is to add the license meta and nothing else. The author might have a good reason for keeping the META.yml file around. One approach would be to discuss with the author if it is good idea to drop it completely.

Missing strict/warnings pragma

This is the easiest of all: one or more modules in the distribution are missing the [strict]](https://metacpan.org/pod/strict) or warnings pragmas. Just add the line use strict; (or use warnings;) at the top of the modules missing them:

package package_name;
use strict;

Is it that simple? Yes and no. If the module uses Moose or Moo then use strict; is enabled automatically, so the additional import is redundant. The module Test::Strict has the strict_ok test function to detect whether a module has enabled strict mode or not (full disclosure, I am the distribution maintainer).

With the warnings pragma, there can be other considerations too. I was giving talk at the German Perl Workshop 2018, during the talk I spoke about one of my pull requests being rejected by the author for adding warnings pragma. At the time I didn’t have the courage to question the author, so I apologized and moved on. Surprisingly, the very same author was sitting in the front row attending my talk! And he was none other than [Reini Urban](). At the end of the talk, he explained to me why he rejected the pull request: in some cases, adding the warnings pragma can reduce how fast Perl executes.

So the moral of the story is, be careful when adding use warnings; line. To be honest with you, I avoid dealing with missing warnings issues unless I know the author personally.

Missing META.json

Sometimes, you will find a distribution missing the META.json file. Recently, I have noticed many CPAN module authors have adopted Dist::Zilla as the distribution builder. I am a big fan of this tool, however if the author is moving from a traditional distribution builder like ExtUtils::MakeMaker then they often forget to generate this file.

There is an easy solution to this problem: just add [MetaJSON] to the dist.ini file, and Dist::Zilla will generate it during the build process.

Missing a minimum Perl version

This is where the build script does not declare the minimum version of Perl it requires. I am now going to show you how to add this information depending on what distribution builder is used by the module author.

In case of ExtUtils::MakeMaker, it is as simple as adding the key MIN_PERL_VERSION as shown below to the Makefile.PL script.

use ExtUtils::MakeMaker;

WriteMakefile(
  MIN_PERL_VERSION   => 5.006,
  ...
);

Whereas if distribution builder is Module::Build then you can do something like this:

use Module::Build;

my $builder = Module::Builder->new(
  requires => {
    'perl' => 5.006,
  },
  ...
);

If it is using Dist::Zilla then you can either explicitly set the minimum Perl version in the dist.ini as below:

...
[Prereqs]
perl = 5.006
...

Or you can use the plugin MinimumPerlFast which will detect the minimum Perl version needed by the distribution:

...
[MinimumPerlFast]
...

If you need any help getting started as a CPAN contributor, feel free to email me and if necessary, we can remote pair program to get you going.