August 2014 Archives

The 19th CPAN Day and the 1st

Yesterday (August 16th 2014) we celebrated the anniversary of the first upload to CPAN by Andreas K├Ânig (ANDK) (as he worked on what became PAUSE). It was the 19th anniversary, but the first that we've marked in this way.

In one day, 107 people uploaded 775 releases, 41 of which were the first uploads of new distributions, and 10 of which were the first upload by new CPAN contributors. The first two numbers were outright records, and the second equalled the previous best. All of those numbers were higher than I expected.

A brief history of CPAN

My project for CPAN Day has been to pull together a history of CPAN:

  • How it was started, and by whom
  • The other services that make up the CPAN ecosystem
  • The key modules that have helped shape CPAN

In best CPAN tradition, this is the work of dozens of people, who patiently responded to my pestering via email over the last few weeks. Thanks to everyone who helped get it to this point.

CPAN Day - start your engines!

CPAN Day (August 16th, UTC) is nearly here. Someone asked me what the goals are, if any, for CPAN Day. When BOOK came up with the idea, we both thought it was an opportunity to celebrate CPAN, but also a chance to reflect on how we got here, and to think about how we can keep driving it forward.

I also saw it as an opportunity to bang on my curation drum — give everyone ideas for how they might improve their distributions, or those of others, and in doing so improve the overall quality of CPAN.

CPAN was created by us, for us, so do whatever feels right to you.

If you do something for CPAN Day, please tweet about it with the #cpanday hashtag.

Try Travis CI with your CPAN distributions

Travis is a continuous integration (CI) platform for github users, which is free to use. You can set it up so that every time you push one of your CPAN distributions to github, Travis will test it against different versions of Perl.

I've only just started playing with Travis, but I can already see benefits for using it in parallel with CPAN Testers. Why not give it a go on CPAN Day? :-)

Specify the min perl version for your distribution

It's a good idea to specify the minimum Perl version required by your distribution. It's useful information for people looking at your code, it's helpful for CPAN Testers (which will report NA for old perls, rather than failing), and it makes the requirement clear to people who are trying to install your module on an older Perl.

Put your CPAN distributions on github

If your CPAN distributions aren't already on github, then I think you should consider adding them. Github is the most popular code hosting service, so it's the first place many people will look for your code.

If your distributions are on github, it makes it a lot easier for people to submit changes (like bug fixes) via pull requests. And if it's easier, it's more likely that people will.

If you do add your dists to github, then you should make sure that you give the repo in the dist's metadata and the documentation too.

Classify your RT tickets on CPAN Day!

Last week I encouraged y'all to fix a bug or two on CPAN Day, either in your distributions, or in someone else's. To help you, I listed the top 20 dists by bugs.

David "never satisfied" Golden pointed out that the table would be more useful / interesting if broken down by severity. So here it is. This also reveals that a lot of tickets don't have a severity set, so on CPAN Day we should sort that out too!

Acknowledge your contributors on CPAN Day

There's a well known saying, "it takes a village to raise a child". I think our equivalent is something like "it takes a community to raise a CPAN distribution". There are very few modules on CPAN that have been purely the work of one person. You get bug reports, pull requests, feature ideas, typos reported by D Steinbrunner, and so on.

All of these interactions nudge your distribution down the road, encourage you, inspire you, and sometimes annoy you. But they all help make your distributions what they are. So on CPAN day, maybe you could acknowledge them in your documentation?

Thank a CPAN author on CPAN Day

It's all too easy to take CPAN for granted, particularly the modules and distributions that just work, and continue to do so year in, year out. Take a moment to thank the author or maintainer of one of your "go to" modules on CPAN Day (16th August).

I tried this: the recipient seemed to like it, and it made me feel good too.

Check your test coverage with Devel::Cover

For CPAN Day, you could check the test coverage for your distributions using Devel::Cover. If your distributions are already covered, or you don't have any distributions, take a look at the coverage results for some other dists on CPAN Cover, and maybe you could submit something for someone else's dist.

Craft the first paragraph of your DESCRIPTION

The DESCRIPTION section of your module's documentation should come after, and provide the narrative for, the SYNOPSIS. In particular, make sure that the first paragraph is a good summary of what your module does / provides. After the abstract, the first paragraph is your most powerful tool in selling your module to potential users.

For CPAN Day (next Saturday 16th August), make sure all your modules have a DESCRIPTION section in the pod, and that the first paragraph is a good summary. And if you do, tweet about it, using the hashtag #cpanday.

Fix your CPAN Testers failures on CPAN Day

If you're a module author, and looking for something to release on CPAN Day, have a look at your CPAN Testers results. If you've got any failures, check the test report(s) and see if you could release an update to prevent those in the future.

Fix a bug on CPAN Day

If you're still looking for something to do on CPAN Day (Sat 16th August), you could fix a bug in a CPAN distribution. It might be a bug in one of your own distributions, but it doesn't have to be — you could fix a bug in someone else's distribution. If their dist is on github you could send them a pull request, otherwise attach a patch to the issue in RT.

Don't be afraid to rename your module / dist

On Saturday I wrote about naming your distribution, and how that should be based on your (lead) module name. ETHER pointed out that if your module is sub-optimally named, then you should also consider renaming your module (and thus probably the distribution) on CPAN Day.

I thought it would be helpful to expand on that, and give some pointers to resources that might help you with naming.

The 'right' name for your CPAN distribution

When you release your module to CPAN, you should make sure that the distribution has the right name. Doing so makes it more likely that all the different tools and systems in the CPAN ecosystem can process your distribution. I'll outline what I mean by that, and how you can get it right. If one or more of your distributions doesn't follow the conventions, maybe you could release a fix on CPAN day?

Get 'CPANTS clean' on CPAN Day

CPANTS bills itself as a "testing service for CPAN distributions". It calculates a kwalitee score for all distributions. It doesn't test the quality of your code, but instead evaluates whether your distribution follows various conventions.

Being 'CPANTS clean' means that your distribution is more likely to behave well with the CPAN toolchain, the ecosystem of CPAN-related services, and ad-hoc tools that various people write.

If you haven't thought of something to release on CPAN Day (Sat August 16th), have a look at your CPANTS author's page.

About Neil Bowers

user-pic Perl hacker since 1992.