Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

jdavidb (1361)

jdavidb
  (email not shown publicly)
http://voiceofjohn.blogspot.com/

J. David Blackstone has a Bachelor of Science in Computer Science and Engineering and nine years of experience at a wireless telecommunications company, where he learned Perl and never looked back. J. David has an advantage in that he works really hard, he has a passion for writing good software, and he knows many of the world's best Perl programmers.

Journal of jdavidb (1361)

Tuesday July 09, 2002
03:03 PM

README

[ #6241 ]

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:

  • README

    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.

  • Module.pm

    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.

  • Changes

    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.

  • INSTALL

    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.

  • Licenses

    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.

  • tests

    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.

  • interactive configuration

    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!

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Man, why should there be a logical structure? That's just crazy talk, man!  ;-)
    • Right! There's More Than One Way to Do It! Fight the power!

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • I think Licenses is unnecessary - RMS can bite my shiny metal ass. As can your lawyer. As long as you have a LICENSE section in your POD (I violate this in several modules though).

    Telling me that Makefile.PL shouldn't prompt though is just wrong. There's a lot of cases where it should. What about optional modules (via ExtUtils::AutoInstall - the recommended way by CPAN testers)? What about locations of things like the httpd when you need to test mod_perl modules (and no, finding it in the usual paths isn't
    • 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

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
      • 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.
    • 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.

      • 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.
        • 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.

          --
          J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • One thing that screwed me up in some of my first releases to CPAN was this note from the PAUSE site [cpan.org]

    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

  • I don't like having information spread over all the different files, so I am tending more and more to put all documentation in well-named and well-placed sections in the Pod. I just generate the README that.

    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.

    • 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

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • It's all too complicated. I would simplify it down completely and make it easier on the author.

    I don't think README files are necessary any more, now that we have search.cpan.org. It's always out of sync with the main module documentation anyway, so move everything there instead.

    Likewise, INSTALL is silly. Everyone knows how to install a simple Perl module thesedays, and if it's tricky, then put more magic code in your Makefile.PL  ;-)

    My recent crusade is against interactive Makefile.PLs. They shoul
    • 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!

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
    • 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.

    Man, you're just going to love this particular example then.

    There's this module that just got uploaded on CPAN. The README with it contains... well: nothing. Nothing at all, except what h2xs put there as an example, I think. Christ. I

    • 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 d

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
    • 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.3 [cpan.org]

      Not only that, but by the looks of it, the module does indeed look very interesting. And now, we can know about it.