Registering Your Namespace

Chapter 5 - Submitting Your Module to CPAN
by?Sam Tregar?
Apress ? 2002
Companion Web Site

Once you have an Author ID, you can log in to the PAUSE system at http://www.pause.cpan.org. There you'll find a link to the namespace registration form under the User Menu (see Figure 5-1). In the form, you'll fill out the information necessary to register your module in the Module List (described in [e-mail].

Figure 5-1: The PAUSE namespace registration form

The namespace registration form requires the following information:

• The module name

• The module list chapter

• The DSLIP code information:

  • D: The development stage (i-idea, c-pre-alpha, a-alpha, b-beta, R-released, M-mature, S-standard, or ?-unknown)

  • S: The support-level (n-none, d-developer, m-mailing list, u-comp.lang.perl.*, or ?-unknown)

  • L: The language used (p-Perl, c-C, +-C++, o-other, h-hybrid, or ?-unknown)

  • I: The interface style (f-functions, r-references and ties, O-object-oriented, p-pragma, h-hybrid, n-none, or ?-unknown)

  • P: The public license (p-standard Perl, g-GPL, l-LGPL, b-BSD, a-Artistic, o-open source, d-distribution allowed, r-restricted distribution, n-no license, or ?-unknown)

• A short description of the module (up to 44 characters)

• A list of places where the module has been or will be discussed publicly

• A list of modules with similar functionality

• Rational

Although highly recommended, filling out this form isn't strictly necessary. Once you have a CPAN Author ID, you're able to upload any module you like so long as you're not uploading a module containing a package name that's already been registered to another author. However, by not registering your module name, you run the risk that someday the folks on [e-mail] will decide to let another author register the namespace out from under you.^[3]

You should expect to receive a reply to your namespace registration request within three weeks. Or you might never receive a reply at all, which means acceptance of your registration request. Yes, really.^[4] As a result, it's common for experienced authors to register and upload in one fell swoop.

Pre-Upload Checklist

Uploading a new module is an exciting experience. It's the culmination of a great deal of planning and development. Unfortunately, that excitement can make for some fantastic blunders. Here's a checklist to help you avoid some of the more common errors.

• Check your MANIFEST. Make sure your MANIFEST file contains all the files in your distribution directory. One way to do this is to run a make disttest, but this will only work if your module's tests are complete enough to notice a missing file. It won't catch a missing README, for example, so it's best to check by hand.

• Make sure your module distribution filename contains a version number. This is a no-brainer if you're using make dist to generate your distribution (and why wouldn't you?). It's worth adding here because PAUSE won't let you upload the same file more than once. If you upload, for example, My-Module.tar.gz, then you'll have a hard time uploading a new version when you fix your first set of bugs.

• Make sure you've updated the version number everywhere. A common error is leaving old version numbers in README or Changes files. This can be confusing for your users.

• Remember to update the Changes file. Savvy (and/or lazy) users will use this file to decide whether or not to upgrade right away. If you fix a problem that might cause the premature heat death of the universe, then you want to make sure your users know to upgrade immediately.

• Test the distribution on at least one other machine. This step can be time consuming, but it definitely pays off. In choosing a test machine, try to find a machine as different from your own as possible. If you're developing on Linux, try installing your module under Windows and vice versa.

^[3]This has never happened, to my knowledge, but if it scares just one author into registering his or her namespace, then it was worth mentioning.

^[4]A search of the [e-mail] archive will reveal that I had to learn this one the hard way. Learn from my mistake!