A few hour after I've released version 1.21 of Pod::Tree Henk van Oers asked on one of the changes that went into the release if I broke it. Specifically he wrote:

Can't locate Pod/Tree/Stream.pm ...
Is the dist compete?

So I went to MetaCPAN and followed the link to the Testers that lead me to the CPAN Testers Matrix and to main CPAN Testers page. (Note, both links include the version number of the distribution and show the date relevant to that version.)

There I could see everything was red meaning all the test reports came in as failures. I clicked on one of the reports and there I could see the error message in more detail:

Can't locate Pod/Tree/Stream.pm in @INC (you may need to install the Pod::Tree::Stream module) (@INC contains: ...

Naturally we can't "install" Pod::Tree:Stream, we are the ones who are supposed to supply that module. So what is the problem?

Apparently, when I factored out the packages to their own files I've forgotten to add the new file to the MANIFEST file and thus they were not added to the distribution.

The tests on my machine passed because the files were in the Git repository. The tests run by Travis-CI passed, because they use a snapshot from the Git repository.

The tests run by someone who downloaded the distribution from CPAN failed, because some of the files were missing.

This means, that since the release of version 1.21, no one can install the module from CPAN. More specifically, the default installation methods cpan Pod::Tree or cpanm Pod::Tree will fail. People can still install an older version of the module, but for that they have to know how.

Luckily this is not a critical infrastructure module and probably very few people have tried to install it in the last few hours, but I'd better fix it soon anyway.

But before that, let's see how could we avoid similar problems in the future? (Well, in the distant future I'll change the system to automatically include all the files that I don't exclude, but for now we don't have that.)

make disttest

In addition to the make-commands we have already seen, there is another command called disttest.

It prepares the directory with all the files that go into the distribution, just as make dist does, but instead of creating a zip-file from the directory, it cd-s into it and runs the tests there. In case we are getting ready to release version 1.21 of Pod-Tree, make disttest create a subdirectory called

Pod-Tree-1.21/ then it will run:

cd Pod-Tree-1.21/
perl Makefile.PL
make
make test
cd ..

This means that if there is a file that need to be in the distribution but isn't then we have a good chance of catching it even before we release the broken package.

You can try checking out the version that was used to build 1.21 and run

perl Makefile.PL
make
make test
make disttest

You'll see the first run of the tests will pass, the second run will fail.

add missing files to MANIFEST

Now that we know how could we avoid the problem, let's fix the problem. I've added the 4 new pm files to the MANIFEST:

commit

Then I ran make disttest and noticed it is much faster than the regular test run. That's what reminded me that I've also added 3 new test-files and none of them were added to the MANIFEST file.

I had to fix that: commit

Release 1.22

Now it seems I was ready to release the new version, and so I did:

commit.

Indexing failed

Within a few seconds I got the first e-mail from PAUSE acknowledging the file-upload and within a minute or so I got a second e-mail with the following subject line:

Failed: PAUSE indexer report SZABGAB/Pod-Tree-1.22.tar.gz

Inside the e-mail the failure report looked like this:

Status of this distro: Decreasing version number
================================================

The following packages (grouped by status) have been found in the distro:

Status: Decreasing version number
=================================

     module : Pod::Tree::BitBucket
     version: undef
     in file: Pod-Tree-1.22/lib/Pod/Tree/BitBucket.pm
     status : Not indexed because Pod-Tree-1.20/lib/Pod/Tree/HTML.pm in
             S/SZ/SZABGAB/Pod-Tree-1.20.tar.gz has a higher version
             number (1.10)

     module : Pod::Tree::StrStream
     version: undef
     in file: Pod-Tree-1.22/lib/Pod/Tree/StrStream.pm
     status : Not indexed because Pod-Tree-1.20/lib/Pod/Tree/HTML.pm in
             S/SZ/SZABGAB/Pod-Tree-1.20.tar.gz has a higher version
             number (1.10)

     module : Pod::Tree::Stream
     version: undef
     in file: Pod-Tree-1.22/lib/Pod/Tree/Stream.pm
     status : Not indexed because Pod-Tree-1.20/lib/Pod/Tree.pm in
             S/SZ/SZABGAB/Pod-Tree-1.20.tar.gz has a higher version
             number (1.20)

So apparently this release was also broken. It was so broken that it could not even be indexed by PAUSE.

It took me some time to figure it out, but the problem was again related to the new modules. Earlier they were in a file that had a version number and PAUSE associated that version number with all the packages in the specific pm file. When I move the package to a separate file that new file did not include a version number. So now PAUSE sees the version number of these packages as undef.

For some, probably obvious, reason PAUSE will not index any module that has a smaller version number than the most recently indexed version of that module. The file will still be on CPAN and people will still be able to install it, but those who rely on the default installation method won't install this release. This seems to be a reasonable security measure.

In the longer run I wanted to fix the version numbers and make the the same in all of the module so now that have to add version numbers to the new files, I can also start doing that.

I quickly added version number to all the modules and release version 1.23:

commit

A few minutes after uploading to PAUSE, I got the two e-mails. The indexing worked.

Actually there were more than 3 modules without version numbers, but apparently those that were without in 1.22, have never had a version number. Now they have.