15.3 Preparing Your Distribution

Once you've gotten your module name settled and you've tested your module with its new name (if needed), you should make sure your distribution is ready for prime time. While this is similar to releasing a distribution inhouse, as described in Chapter 14, you might want to ensure a few additional things about your distribution:

• Create a README file. This file is automatically extracted to a separate file on the CPAN archives and lets someone view or download just the key facts about your distribution before fetching or unpacking the rest.

• Make and test your Makefile.PL. Modules without a Makefile.PL are accepted via PAUSE to go into the CPAN but usually get a grimace from those of us who download your stuff because we might have to figure out how to build and install your distribution.

• Bring your MANIFEST up to date. If you add files that should be part of the distribution, they also need to be in the MANIFEST. One quick trick is to clean things up as you would want them in the distribution, and then invoke make manifest, which updates the MANIFEST file to be exactly what you are holding at the moment.

• Have a logical distribution version number. The Makefile.PL file should specify either a VERSION value or a VERSION_FROM value. If you have a single module (such as a .pm file) in your distribution, it's usually best to grab the version number from there with VERSION_FROM. If you have multiple files, either designate one of them as the one you'll always update just before a new release or use the VERSION within the Makefile.PL instead. Also keep in mind that your version number must always increase numerically for newer versions of your distribution.

• Have tests! Reread Chapter 14 if you must. There's nothing that builds more confidence in an installed distribution than at least a few dozen tests that are run during the installation phase.

• Invoke make disttest, which builds a distribution archive of everything in MANIFEST, unpacks the archive into a separate directory, and then runs the tests on your distribution. If that doesn't work for you, you can't expect it to work for anyone else who downloads your distribution from the CPAN.