Example modules are no longer indexed by PAUSE

PAUSEPermissions Tue 2 August 2016

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.

What happens when you upload a distribution?

When you upload a tarball to PAUSE, the following things happen:

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?

Skipping parts of a distribution

When looking for .pm files, PAUSE was already skipping the following directories in a distribution:

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.

Problem 1: example modules being indexed

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 XML::AIML::Li. 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 XML::AIML::Li

The 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 XML-Toolkit again. Oops.

Problem 2: permissions for example modules

Because example modules were being indexed, they were first being checked for permissions. Unsurprisingly people often use similar names for example modules, like Example1.pm, or Testclass.pm. 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.

PAUSE no longer indexes example modules

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. I use examples, as I think that's clearest.

comments powered by Disqus