A recent change to PAUSE means that examples included in a CPAN release are no longer scanned for package names to index, and aren't checked for permissions. This simplifies the rules about indexing and permissions, and also helps us resolve some historical permissions conflicts. In this post I'll present the problem(s), explain what has changed, and what this means for CPAN authors.
When you upload a tarball to PAUSE, the following things happen:
authors/id/Z/ZA/ZAPHOD. Author directories are copied onto all CPAN mirrors.
.pmfiles. A module called Foobar will usually (but not always) be in
lib/Foobar.pm, and somewhere near the start you'll find the line
package Foobar, but it may have additional cuckoo packages defined in the same file.
There are a bunch of other things that might happen; you can read about some of them here: what happens when you upload to CPAN?
When looking for
.pm files, PAUSE was already skipping the following directories in a distribution:
xt: libraries in test directories are just used when running tests, and aren't installed.
incis the conventional directory where you put modules needed by your module builder / installer, particularly Module::Install.
fatlibare all used by some part of the toolchain, and any modules in there aren't installed.
So from this, you can see that the general rule should really be: if a module isn't going to be installed, then it shouldn't be considered for indexing.
Many distributions include example modules and scripts,
to illustrate how to use the public module(s)
in the distribution
(ie those that are installed).
For example, Chris Prather's XML-Toolkit distribution
contains a lot of public modules, but also many example modules, such as
Because example modules were being indexed, this latter module was appearing in the CPAN Index:
XML::AIML::Li undef P/PE/PERIGRIN/XML-Toolkit-0.15.tar.gz
This meant you could try and install it with a CPAN client:
cpan client would find XML::AIML::Li in the index,
notice that it hasn't been installed,
map it to the release shown above,
and install that.
But because example modules aren't installed,
XML::AIML::Li wasn't installed.
If you run that
cpan command again, it will see that the module still hasn't been installed, so will install
Because example modules were being indexed, they were first being checked for permissions.
Unsurprisingly people often use similar names for example modules, like
If you were the first person to use that name, then you'd get ownership, and your module would be listed in the index.
Anyone else using the same example package name would get an email from PAUSE telling them they didn't have permission
for that package (the rest of their distribution would probably be indexed ok).
In the past someone else might have included an example called
example1.pm (note the difference in case),
and because PAUSE used to treat package names case sensitively, those were treated separately for permissions and the index.
Now they're treated as the same namespace for permissions, resulting in a conflict.
That's what led me here: I'm working on resolving all such conflicts in PAUSE permissions.
But really there's no need to enforce permissions on example modules, as we've already established, because they're not installed.
When looking for packages to index (and thus check for permissions),
PAUSE now no longer considers example modules.
Specifically, it ignores
.pm files in the following directories:
In most cases you don't need to do anything as a result of this change, and if you have a conflict case, then I'll be getting in touch with you eventually anyway.
There are other directories we should be ignoring as well, to make sure that what gets indexed is aligned with what gets installed. That's now on my long-term todo list to loop back around on, but first I need to finish working on the permissions conflicts.
If you want to include example modules in your distribution,
please use one of the directory names listed above.
examples, as I think that's clearest.