NEILB's Blog

You've been handed a random CPAN distribution and been told to do something with it. But what? In this brief post I'll outline a high-level way to consider your options, and what to do for each option, with pointers to online resources to help you.

Faced with a random distribution, I think these are the top-level options:

Let's look at those in turn, but first, always remember that someone else has put their time and effort into the distribution, so treat them and their work with respect.

Improve it

There are a number of ways a distribution can be improved, but broadly:

• Click on the "Issues" link in the left-hand sidebar on MetaCPAN. It might say 0 (zero), but still click on the link, as MetaCPAN's count is only updated daily. If you were taken to RT, then go to the github repo as well, and see if there are any github issues.
• Refactoring is worth a whole series of posts on its own. Remove or change dependencies, rewrite code to be clearer, update to follow modern / best practices. Change from Moose to Moo (talk to the maintainer before you take that on), and more.
• Tests: improve coverage, switch to modern Test:: classes, look at test failures on CPAN Testers.
• There are many ways you could improve the doc, some of which are listed here. A good one is to add a thorough SEE ALSO section.
• Is there an examples directory you could add an example to. Would the dist benefit from having one?
• Improve the distribution itself: add structure to the dist, for example if it doesn't have lib/ or t/ directories. CPANTS should be your first port of call, when looking for issues in this category. Go to the maintainer's summary page. For example my page is cpants.cpanauthors.org/author/NEILB.

Deprecate it

This basically tells people not to use the distribution, for example if they find it on MetaCPAN. Add the word "[DEPRECATED]" to the abstract, and repeat that fact in the first paragraph of the DESCRIPTION. If there's one or more modules that are better to use, then list those at the start of the documentation.

You can also mark the distribution as deprecated in its metadata, using the x_deprecated symbol. A separate article or blogpost will describe how to do that. If you're using Dist::Zilla you can just put [Deprecated] in your dist.ini, using the newly minted Dist::Zilla::Plugin::Deprecated from ETHER.

If a dist appears to be deprecated, but doesn't have all of the above signs, then first check with the maintainer, then do a pull request (PR) which fully deprecates it.

Do nothing

There are very few distributions on CPAN that can't be improved on some way, but there will be some. For example:

• It's already deprecated, but can't be deleted yet.
• Everything that can be done has been done.

If you think a dist might be in this category, first propose it, for example in the #pr-challenge channel on irc.perl.org, or on the cpan-pr-challenge mailing list.

If there's agreement, let me (NEILB) know please, so I can mark it as such in the database, so it won't be assigned to anyone again.

Adoption

Sometimes there are things that could be done with a module, but the current maintainer is longer interested in the module, is too busy, or can't be contacted. In that case, it might be a candidate for adoption, where someone new takes on mainenance of the distribution. It doesn't have to be you, you could propose it for adoption on IRC or in the mailing list. One of the first steps is to email the maintainer.

Remove it from CPAN

Can this dist be removed from CPAN? If there are other dists using it, then it's a quick "no" (click on the 'Reverse dependencies' link when looking at the dist on MetaCPAN).

This option needs to be considered carefully, but some examples where I think a module can safely be removed:

• It doesn't work and has never worked.
• It was last released years ago, there are no other dists using it, and there are better modules for doing the same thing.
• It's been deprecated for a good while and there are no other dists using it.

If you think a dist should really be removed, but it doesn't quite meet the criteria, then it could be deprecated first, and removed later.

Other articles: deleting distributions from CPAN, curating CPAN sometimes means really deleting stuff.