Friday, January 9, 2015

How to make your first contribution to CPAN - the first steps

The first thing we want to try to do is to make a small change to an existing module.

If you already know what you'd like to contribue, that is good. If not, you may be able to find ideas at https://github.com/CPAN-PRC/resources

I was assigned to the DateTime::Format::Pg module.

On the MetaCPAN page, I see that the code is hosted on github at https://github.com/lestrrat/DateTime-Format-Pg/blob/master/lib/DateTime/Format/Pg.pm

The first step is to follow the instructions at https://help.github.com/articles/fork-a-repo/ and to get a copy of the code on your box.

Next, we need to run the tests, and make sure they pass. We also need to check that all the dependencies for this module are installed. We do this in different ways depending on which build system the module uses. If we find a Build.PL in the module, then we use

perl Build.PL
./Build test

If we find a Makefile.PL, then we do
perl Makefile.PL
make test

If we find a dist.ini, then we first have to make sure we have Dist::Zilla installed. Then we run

dzil test

If we want to run only the tests, but we have the module already installed, then the tests will use that module and not the code that we pulled from github. To make sure we run the tests on our code, we use the -Ilib switch.

prove -Ilib t/*

If you get all your tests passing, you can start adding more tests to this module and then change the code as you see fit.

If you're stuck at any stage, jump onto #pr-challenge on irc.perl.org, and ask for help. You will find some very helpful people there.