There's an immense amount of variation over what goes into the package documentation for a module. Here's what I think should be in each file:
Your README file should tell me what the module is. It functions as an abstract: an abbreviated description of the module, a few paragraphs long. Most importantly, the README should tell me why I might want to use your module. I'm reading these via search.cpan.org's recent page, here, so don't assume I found your module because I was looking specifically for it. In particular, if your module is an interface to the JabXL C library, include a sentence or two telling me what the JabXL C library is for and pointing me to its homepage (or whatever).
The README should not include your module's documentation. That's what the embedded POD is for. The README should not include installation instructions. That's what the INSTALL file is for.
Your README should definitely not consist solely of module installation instructions.
Here I should find documentation for the public interface (API) to your module. This is "how to use it" for a programmer. Use POD. Check it with pod2man and perldoc, one or both of which will bark at you to remind you of what sections you need.
Installation instructions don't belong here, either, especially not at the top. I may read this once before installing, but I will read it hundreds of times after installing.
This might be every single little commit, or it might be a list of major changes for each version. I prefer the latter. Whichever you choose, you should put new entries at the top, so that the older versions are way down at the bottom of the file. It will make it easier on you and on me.
The GNU project calls this file ChangeLog.
The third-edition camel provides a much better introduction to installing modules than ever before. Module installation used to be sort of a black art from a newbie's point of view. It ought to be almost the same for every single module, but module authors of yore used to have to document the whole process or face answering "How do I install? What if I'm not root?" all the time. (And they had to document how to install for Macintosh, and every other little variation.) Many of us slowly learned the ins and outs of module installation by reading the documentation of several modules over a period of months or years, while today's newbies (lucky young whippersnappers) can learn what they need to know all in one place from the camel or the perlmodinstall page. And learn how to put it in their $HOME's, to boot.
Installation instructions don't belong in the README or the POD, but if you cannot suppress the urge, please put them at the bottom so I don't see them. A simple note at the top explaining that the installation instructions are at the bottom is acceptable. Those files should definitely have something else in them, too.
The GNU autotools produce a generic INSTALL file that works for most ./configure programs. Makefile.PL is different, but we could still use a similar boilerplate file for Perl modules. Until such a file is written and integrated into h2xs (or whatever succeeds it), please provide an INSTALL file with installation instructions, and mention "To install this module, follow the instructions in the INSTALL file that came with this package," at the top of your README.
Oft forgotten, the license files can be important in several ways. Please explicitly state what terms your module is available under, to satisfy corporate lawyers in other people's organizations so they can use your code.
In general, your module will probably be "free software" available under "the same terms as Perl itself," which means people can redistribute your module under the terms of either the Perl Artistic license or the GNU General Public License. If you want your module made available under different terms (just one of the two, or a different license entirely), stating your terms becomes even more important.
Assuming you choose the normal terms, please include the complete text of both licenses. New users (and the lawyers that obstruct them from doing their jobs) may not be familiar with the concept yet. In addition to reassuring them that it is okay for them to use your module in any way they want, this is a great opportunity to introduce them to the world of open source. The Perl Artistic license was the first open source license I ever read, and I remember thinking, "Wow! If I ever write anything worthwhile, that would be the way to release it! Shareware's such a waste, but this means other people can really do whatever they want with the program!"
The GNU project recommends you put a copyright and license notice at the top of every source code file, and include the GPL text, traditionally in a file named COPYING. The Artistic license is traditionally in a file named Artistic. I would put this notice in a comment at the top of each file of code: "This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself." You should make reference to the COPYING and Artistic files somewhere, preferably at the end of the module POD documentation.
You should have tests. They should pass. :) After you upload your module, please try installing it with CPAN.pm and make sure the tests still pass.
Your Makefile.PL shouldn't ask any questions. It should determine things either on its own or by taking input on the command line. I want to run perl5.6.1 Makefile.PL && make && make test && make install on one line, go off somewhere for ten minutes, come back, and then play with your module. I don't want to come back to find that nothing happened because the module is prompting me to enter a configuration option. Consider also what will happen when a user tries to install with CPAN.pm and cannot provide this input. Configuring your module may be so complex a task that it cannot be installed with CPAN.pm, but please don't make it so unless it has to be.
In general, think about when each file will be read and by whom. There shouldn't be a whole lot of overlap between each of the items I listed, with the possible exception of brief pointers to the appropriate location.
Please help save the world! Please encourage me to use your module when I see it on search.cpan.org/recent!
Re:Crazy Talk
jdavidb on 2002-07-09T22:52:34
Right! There's More Than One Way to Do It! Fight the power!
Re:Hmm
jdavidb on 2002-07-09T22:50:41
Prompting: well, like I said, it's not always possible. But if you can get those things into command line arguments it means I can decide them all up front and come back to that window after lunch. (It also makes it easier to put modules into core. The main perl source has recently eliminated one of the last interactive prompts (at install time). Of course, you may never want your mod_perl modules in core. :) ) If someone's installing something as complicated as a mod_perl module, I'd say there's a good chance it doesn't need to run unattended or through CPAN.pm, anyway, so all bets are off. But the vast majority of Acme::Bleach and YA::Sort modules don't need to prompt me for such things as installation prefix.
I figured licensing would be controversial. :) I don't personally have the lawyer problem, but I figure some people might. (To some of us, pissing off the lawyers is worth MORE than having someone use the code. It's all a question of priorities. :) ) In my case, I just sometimes wonder about a module with no indicated terms. Minimally, if the three letters "GPL" or "BSD" appeared somewhere, it would at least indicate the intent. There's been talk occasionally that you can't really produce an honest CPAN CD because of vague or unspecified licensing. (And, worst of all, "This module is under the GPL except that you may not include it on a CD." Another pet peeve...) In context my original concern (that didn't come out in the writing; too many trains of thought) is that your license best goes in a separate file like that. End of POD is okay. Beginning is going to make me curse your name every time I read your docs. :) And, I've never seen it, but I'm sure one day there will be a Makefile.PL that prints out the full text of the GPL.
Re:Hmm
Matts on 2002-07-10T08:56:36
I *think* ExtUtils::AutoInstall allows some command line flags to either install everything or install nothing. Not sure though.
As for CD makers, they should take some more time and effort over it - contact the authors of things you want to put on there, and offer them a free copy ferchristsake. The CPAN is a free resource and everyone can get it, so don't try and con people into thinking that it's a massive bonus to be able to get a version of this software without downloading it.Re:Hmm
Dom2 on 2002-07-10T13:36:27
Sorry, Matt, you're completely wrong. Any questions that your Makefile.PL needs should be supplied on the command line or in environment variables. If it can't autodetect what it needs then it should die and say so.
Non-Interactivity is an absolute necessity when you're building packages from modules and expecting them to work.
If you want to do clever stuff, let the advanced user that needs to do it read the damn docs and figure out how to do so. Optimise for the common case by not asking questions.
Re:Hmm
Matts on 2002-07-10T14:04:21
I'm not WRONG. I just have a different opinion to you.
Writing installers is probably the hardest part of every single software project I've ever worked on. Period. This is not something Open Source developers need to be wasting their time on when they can ask questions and have an easier life.
Feel free to supply patches.Re:Hmm
jdavidb on 2002-07-10T15:28:48
Feel free to supply patches.
That's the real answer. "Right" and "wrong" are really defined by the module author. If someone else wants it another way, is willing to do the work, and the module author doesn't mind, great!
But I think you'll find most of us increasingly prefer non-interactive installations.
Re:Hmm
Matts on 2002-07-10T16:54:22
We all *prefer* non-interactive installs.
Do not upload the READMEs that are integrated in your distribution files. PAUSE is designed to take care of unwrappig your file with tar or zip, registering all the modules it finds in there, and placing the readme file (i.e. a file with the name README in the top level directory of your package) into your directory. PAUSE will change the name of the file to package-name.readme. It should do so within a few hours after your upload.
This is, as far as I know, complete bullshit.
Re:README files
koschei on 2002-07-10T04:43:51
Are you sure? It's always correctly extracted mine. Follow this link for a link to my section of CPAN.
Re:README files
djberg96 on 2002-07-10T12:39:21
Hmmm...upon further review, I may have misunderstood what this paragraph means. Where's the "delete comment" option?
Since I say the Pod must always start with why you should use the module, that makes for a relevent README.
This approach also simplifies things for makepmdist and its users.
Re:README et al
jdavidb on 2002-07-10T03:35:27
That makes sense, too. The main thing is, I hate looking at a module, thinking, "What does that do?" and then reading installation instructions or licensing info in the README. :) Secondarily, I hate looking for something in the place where I expect it (Changes, for example) and not finding it, and having to search through three other files to find out where s/he put it.
So a relaxed generalization of my preferences is, "Put what I want in the place where I expect it. Other stuff is cool, if it's short pointers ("at the bottom of this file") or ("see file FILENAME for further info"), or down at the bottom so that I see what I'm expecting at the top.
The POD should start with why you should use the module. Vigorous agreement from me. To me the README is an abstract, and if you did a good job of the POD, I think the first few paragraphs of it should suffice for that abstract.
Another thing I saw after I wrote the rant: don't start the "DESCRIPTION" section of the POD with bugs or missing features! How can I know it's a bug or missing feature when I don't even know what the module does yet? :)
Re:Too complicated
jdavidb on 2002-07-10T13:24:59
My recent crusade is against interactive Makefile.PLs.
Woohoo! Somebody agrees! :)
Everyone knows how to install a simple Perl module thesedays
Exactly my point. I know, and I'm tired of reading it where a description of the module should be. I personally wouldn't be affected at all if there were no installation instructions with the module.
Been thinking about trying out Gentoo. It seems to provide all the benefits of LFS and Debian, and I hear it will work on my iBook!
Re:Too complicated
Dom2 on 2002-07-10T13:42:13
I'm totally with you on non interactivity. It's exactly the same reason that I hate perl's default Configure script. I just want to come back and find it built, or find an error telling me why not.
If you want some hints about getting CPAN integrated with a packaging system, you might want to look at the BSDPAN stuff that's included in FreeBSD-CURRENT. I haven't used it, but it's meant to auto-package CPAN modules into FreeBSD packages when they're installed via CPAN.pm.
The README should not include your module's documentation. That's what the embedded POD is for. The README should not include installation instructions. That's what the INSTALL file is for.
Your README should definitely not consist solely of module installation instructions.
Re:This got uploaded to CPAN just today...
jdavidb on 2002-07-16T21:31:44
I know. What do you think prompted my rant?
:) [This is by no means the first module to do this.] I think h2xs shouldn't say that the README should include installation instructions, because I don't think that's where those instructions should go. Or, at least, they should be shoved down at the bottom under the "Why do I want to use this module?" part.
Petal is sort of a bad name for a module, too. Great name for a program. Maybe it's a huge configuration management system. Maybe it's an automatic database optimizer. With a program, you want a trademark-ish name like that. With a module, your module name should say what it does: Database::Optimizer::Automatic.
(More or less. There's plenty of popular modules with non-descriptive names that get by because we all know what they do.)
Re:This got uploaded to CPAN just today...
bart on 2002-07-20T22:34:22
Well whatdayaknow... 3 days later, and there is a new upload for Petal (uploaded yesterday), and this one does have a proper readme file...
Readme for Petal 0.3Not only that, but by the looks of it, the module does indeed look very interesting. And now, we can know about it.
