The CPAN ecosystem is more than just a way to share your code with other people. It’s also a way to let other people collaborate on the code and to help you release it. In Item 70. Contribute to CPAN, you saw how to upload your work to the Perl Authors Upload Server (PAUSE). There’s a lot more that you can do through PAUSE, though. Even if you aren’t a CPAN author, you can use PAUSE to find out more about a module’s authors and comaintainers.
Some definitions
There are several points to consider as you try to figure out how PAUSE works. Start with the defintions to ensure you’re thinking about the same things as you go through this Item. People are often quite loose with their terminology, so its useful to define these terms before you get started.
A module is a unit of Perl re-usability. It’s typically a single .pm file, but it might be more than one if it loads private plugins or other helpers. You load a module with do (rare), require, or use.
A package and a namespace are almost the same thing, but not quite. The package is really all the bits that live under a particular namespace, with is just the name you gave to the package. You declare a default namespace with the package built-in. You can affect the package in any file, but the namespace is just the label. A “module” and a “namespace” are often interchangeable terms because most modules use a single namespace, or at least a single, advertised namespace.
A distribution is a collection of modules or programs, along with ancillary files and installation information, turned into a single file with an archiving tool such as tar or zip. A distribution can contain several modules. In other words, the distribution is the thing you upload and share. Some people use “distribution” to refer to any of the releases with the same base name, such as Moose-1.01.tgz, Moose-1.02.tgz, … Moose-1.21.tgz.
PAUSE indexes a distribution by recording the namespaces and versions it finds and adding them to the database that produces the file modules/02packagedetails.txt.gz, which CPAN clients use to figure out what to download when you want to install a module.
PAUSE only cares about uploads
PAUSE is really just a release mechanism for CPAN. You upload a distribution, PAUSE looks at the namespaces you declare with package, and looks up those namespaces in its database. If it thinks you are allowed to upload those namespaces, PAUSE indexes your distribution. It examines the version numbers for the packages, and as long as the new versions are greater than the previous version values in the index, PAUSE adds your distribution information to its database.
If any of that fails, PAUSE sends you an email explaining what went wrong. PAUSE still puts your uploaded file in your author directory, but since PAUSE doesn’t add the unauthorized namespaces to the modules/02packagedetails.txt.gz, CPAN clients won’t see it.
There are several sorts of maintainers
To PAUSE, a maintainer is someone who can upload a distribution that PAUSE will index. The role is more like a release manager. You don’t have to be a PAUSE maintainer to work on and collaborate on CPAN code.
If you need to get something fixed and uploaded, there are two types of maintainers that may be able to help you: a primary or co-maintainer. There are some additional classifications of those, too.
You can be a primary maintainer or a co-maintainer of a namespace (not a distribution). The primary maintainer can assign or take-away co-maintainer permissions, as well as pass on primary maintainership to someone else (while losing that status in the process). PAUSE will index the namespaces in a distribution uploaded by any of these maintainers.
If you are the first person to upload a distribution using a particular namespace, you are a first-come maintainer. PAUSE assigns that namespace to you merely because you are the first person to use it. You don’t have to ask anyone’s permission or give any notice to use a new namespace. PAUSE, being mostly automated and mostly code, doesn’t care anything about your namespace other than it being new.
You can also add a co-maintainer for a namespace, which is really adding what most people would consider a release manager. By assigning co-maintainer permissions for a namespace, you tell PAUSE to index that namespace if that co-maintainer uploads it. As a co-maintainer, you do not have to upload the assigned namespace as part of the same distribution though. That shouldn’t be a common, or even intended, sort of upload though, and is likely to confuse people when they don’t get the distribution they expected.
There are two less-known types of maintainers too. A primary maintainer can also be a module list maintainer. That means that the maintainer registered the namespace with PAUSE. No one needs to register a namespace, but there are some some PAUSE features that only work with registered modules. For instance, you can register a namespace to “reserve” it for future use without uploading a distribution that uses that namespace.
Beyond that, there is also a mailing list maintainer. This is like a primary maintainership shared among anyone in the mailing list. Any one of those persons can assign or take away co-maintainer permissions. Projects such as PARROT and PERLCRITIC use the mailing list feature because they rotate release managers.
Find a maintainer
Any of the maintainers can upload a new distribution that PAUSE will index. That means that when you need to get something fixed, you may be able to find more than one person who can help you get a bug fixed and uploaded. Note, however, that you should also try the advertised support of the distribution, including its issue tracker (most likely CPAN RT), its mailing list, and so on. As you read earlier, maintainers are really just release managers so there may be other people who can work on the code.
If you have a PAUSE account (Item 70. Contribute to CPAN), you can use the PAUSE interface to search the permissions database. You can search by the maintainer name, the exact module name, or use a string for an SQL LIKE query. The results for any search allow you to drill down into the results by the namespace or the author name.
If you don’t have a PAUSE account, you can still look through the permissions for all of the namespaces. A couple of years ago, PAUSE added the $CPAN/module/06perm.txt file which lists each namespace:
File: 06perms.txt
Description: CSV file of upload permission to the CPAN per namespace
best-permission is one of "m" for "modulelist", "f" for
"first-come", "c" for "co-maint"
Columns: package,userid,best-permission
Line-Count: 175031
Written-By: Id
Date: Sun, 19 Dec 2010 09:08:52 GMT
A,ADAMK,f
A::B,CODEREPOS,c
A::B,MARCEL,f
AA,RLZWART,f
AA::GAMP,RLZWART,f
AAA::Demo,JWACH,f
AAA::eBay,JWACH,f
AAAA::Crypt::DH,BINGOS,f
AAC::Pvoice,JOUKE,f
AAC::Pvoice::Bitmap,JOUKE,f
AAC::Pvoice::Dialog,JOUKE,f
AAC::Pvoice::EditableRow,JOUKE,f
AAC::Pvoice::Input,JOUKE,f
AAC::Pvoice::Panel,JOUKE,f
AAC::Pvoice::Row,JOUKE,f
The $CPAN/module/06perm.txt has three fields: namespace, PAUSE author, and the type of permission. The one-letter permission code is explained in the file header. Using grep or a Perl one-liner as a poor man’s query tool is often sufficient to find what you want:
As a bonus, notice the use of the -a and -F switches to perl. The -a autosplits each line using whitespace as the delimiter. However, if you use the -F switch, you can specify an alternate delimiter. Either way, the results end up in the @F array.
In this example, you use -F to split on a comma then match against $F[0] to find namespaces:
$ perl -F, -ane 'print if $F[0] =~ /^CPAN::/' 06perms.txt
If you wanted to find an author, you can look in $F[1]:
$ perl -F, -ane 'print if $F[1] eq q|BDFOY|' 06perms.txt
You don’t have to be a maintainer to work on the code
Although the term “maintainer” implies that you also work on the code, some maintainers do nothing more than uploading the distribution. Likewise, not everyone who actually maintains or works on the code needs co-maintainer permissions in PAUSE.
You don’t own heirarchies
When PAUSE assigns you a namespace as a primary maintainer, you only “own” exactly that namespace. Although Perl namespaces look like they are hierarchial, they aren’t. That is, there’s nothing in Perl that cares what namespace you use or which one your package inherits from. The XML::Simple namespaces doesn’t inherit from XML by virtue of its name. In the same way, you don’t have any permissions on Foo::Bar::Baz merely because PAUSE assigned you permissions on Foo::Bar. That means you don’t have to rush to register your company’s name as a namespace because it’s not going to prevent anyone from using it for another namespace.
As part of the lack of proper heirarchies, you also have to assign comaintainer permissions on every particular namespace that you want to share.
Fix your “unauthorized” release
Even if PAUSE does not index your distribution, it still puts it in your author directory. The CPAN servers still mirror everything in your author directory, just like they mirror old distributions that do not appear in the index. The CPAN Search website still shows the distribution but puts a big red UNAUTHORIZED next to the distribution name and also the namespaces with the missing permissions:
To fix this, you need to get the missing co-maintainer permissions. The primary maintainer or the mailing list members will have to help you with that. As a last resort, you can ask the admins at [email protected] for help.
Things to remember
- A PAUSE or CPAN author is really a release manager.
- A primary maintainer can assign co-maintainer permissions.
- You can search permissions through the PAUSE interface.
- You can search permissions in the $CPAN/modules/06perms.txt file.