I've been wrangling with the lack of documentation on how to start a module that one would expect CPAN inclusion at some point. Not that the docs aren't there, but there's nothing coherent to them and are spread throughout time and space, at least in the standard perl documentation space (including info from CPAN and PAUSE). While learning by example (other CPAN modules) works, it's not always intuitive. So I am considering at least putting a tutorial or a howto together on how to go about doing this, partially for myself, and partially for the community as a whole.

Note that if you have a better reference already, please let me know, I'd rather not reinvent the wheel.

The steps, as I see it (and will be trying in the very near future) appear to go along these lines:

Use "h2xs" to create a 'new' perl project within a new directory; if not using
any lib stubs, the -X will only create perl files. This includes Makefile.PL, README, and test.pl

Create/move the library files into place in this new
directory, making sure to define $VERSION

If tests are desired, either create them in test.pl, or delete test.pl, create a directory 't', and within 't', name any scripts that are part of the test suite as '*.t'.

use "perl Makefile.PL" to create a unix-compat makefile.

Edit README and other document files to liking.

At this point, one has a nearly complete package; at this point, a program like CVS can be used to maintain version control.

Use "make; make build; make test" to make sure everything works as expected, and edit as necessary.

Use "make clean" to return to a distribution-ready directory structure.

Distribute as necessary.

Obviously, this doesn't cover a large number of possible situations, but from what I can tell from the docs, this is sufficiently adequete for perl-only modules. Am I missing any key steps, paying too little or too much attention to certain steps, or just am thinking completely wrong about this?

h2xs automatically creates a MANIFEST file. I don't use it;
I delete it. I like using 'make manifest', because it automatically
generates a MANIFEST file for me when I want it. To do this,
set up a MANIFEST.SKIP file. Here's an example of a standard
one I use:

With this in place, I don't have to maintain a list of all my files;
'make manifest' will start at the current directory and assemble
a list of all files not matching the patterns in MANIFEST.SKIP, then
write the names of those files to MANIFEST.

I keep my MANIFEST.SKIP under source control but that's not
really necessary.

What is 'make build'? My Makefiles don't have a 'build'
target.

You might also want to get into some of the interesting things
you can do with a Makefile.PL. You can make it sort of a 'configure'
for your distribution.

As an example, the Makefile.PL for Net::SSH::Perl lets
the user choose whether to install the prereqs for SSH-1 or
SSH-2 (or both), which means that if the user really only wants
SSH-1 support, he/she doesn't have to install a bunch of modules
he/she doesn't need. Of course, this also means you have to
learn to love using require in your code, for runtime loading
of modules. :)

Another useful Makefile.PL "trick" is to a "does user have this
module installed?" function:

This allows you to do your own prerequisite checking in
Makefile.PL, because unfortunately, the prereq checking in
the CPAN module depends on having an explicit list of args
to PREREQ_PM; it actually parses your Makefile.PL to look for
such a list. If you have, for example, this:

The best source I've found for this is the chapter called "Writing Packages and Modules" in my favorite Perl book, Effective Perl Programming by Hall and Schwartz. I recommend it highly (the chapter as well as the rest of the book).

Your list contains many of the same items in the chapter, with some differences. For example, I don't think it makes any reference to using version control, although that would be a logical and useful addition. (I'm not certain whether it refers to version control or not -- I don't have the book with me right now.) They do include more specifics on PAUSE and registration, along with URLs to use to check for newer information.

Are there examples anywhere of what goes into a test suite? How should one build it? Are there any gimmes&gotchas to building test suites? I think it would be neat just for maintenance of personal packages...

What goes into tests is easy: this is the same concept as unit testing for object-oriented languages (C++ and Java). Basically you want to test every 'reasonable' object and function to make sure they work in every 'reasonable' test case that you can think of. While this can be a pain to add after your main program is said and done, the concept of unit testing is that these types of short codebits would be developed while you are developing the classes and functions, so inclusion into the test portions is trivial.
Tests should basically make sure you are getting expected results from functions and code, such as:

Now, what you actually print out is still a bit of a quandry for me; I know that there's info about it (that I happened upon luckily) at perldoc Test and perldoc Test::Harness. From my understanding (please correct me) is that the testing process sits at the end of STDOUT and intercepts everything. The first thing that the test scripts (as a whole) must print out is a "1..N\n" string, indicating the number of tests (=N). Each test then should print out "ok M\n" or "not ok M\n", where M is the specific test number. The test code runs all tests regardless of failures of previous ones, and reports the fraction of tests that failed at the end of the test cycle. When you install from CPAN, you'll see those test modules in action.

And again, from the docs and other module examples, you either want one full, comprehensive test in the ./test.pl file, or several small test files in ./t/*.t. In the latter case, tests are run in sorted order, which is why many people name files like "01test.t" as to have the specific tests executed in a logical order while still having the name printed out when CPAN-installing.