Max Maischein

In which I show the tools that I use to clean up and cut releases

In the 12 years I've done CPAN releases, I have acquired my share of experience through botched releases of modules. Much of that experience has dribbled into tools and a release process that is mostly automated to allow me to release a module at the end of a hacking session without needing any mental strength to remember things. My judgement also gets clouded when I'm fixing a module in anger, so having Perl keep me honest and preventing the more obvious failure modes is highly convenient then.

Over the years, I have grown fond of the following automated author tests which I keep in .t files:

• xt/99-changes.t - This test checks that the Changes file contains the version number of the module, a release date and hopefully one or more items that describe what changed between the previous release and this release. This test prevents releasing a new version without telling the users what changed.
• xt/99-compile.t - This test checks that all files below bin/ , scripts/ examples/, blib/ and lib/ compile without warnings. This test prevents shipping syntax errors or unintended variable redeclarations.
• xt/99-manifest.t - This test checks that the MANIFEST exists and all files listed in MANIFEST also do exist. This test prevents later errors when unpacking the distribution and ExtUtils::MakeMaker complaining about missing files.
• xt/99-pod.t - This test checks that the Pod documentation of the module is well-formed. This test prevents the most nasty documentation layout errors. It certainly doesn't ensure nice or even usable documentation.
• xt/99-todo.t - This test checks that no lines containing comments like XXX or TODO are in the release. This test prevents releasing modules with nasty open issues that are only documented in the code as helpless comments.
• xt/99-unix-text.t - This test checks that all (Perl) files have Unix newlines as line endings. This text especially prevents releasing mixed-line files, a problem that haunted me for a while because I was using text editors that didn't properly detect and switch to the proper style of newlines for a file.
• xt/99-versions.t - This test checks that all version numbers within a distribution match. This prevents forgetting to bump the version number for a file even though it has changed. This test does actually enforce bumping the version number even for files which have not changed at all, but I consider that a much better failure mode than having two files with the same name and same version number but different content.

The author tests are complemented by one test that is to be run by every tester, t/00-load.t. This test simply loads the main module and then outputs the version numbers of all loaded module. This is less a test of itself and more a diagnostic tool to allow a user with a problematic setup to easily report on the version numbers of all relevant modules.

The author tests and the module tests are run by prove from the Test::Harness distribution.

Tieing together the Perl modules and the test files is the Makefile.PL, which also gets copied from any older distribution to the next one. The skeleton was provided by Alexandr Ciornii, and optionally does creation of README.mk and a documentation page for all examples shipped with the distribution.