ABOUT CPAN+changelog.pl
=======================
Date: 2006/03/28


- AUDIENCE

If you are administrator for a Perl installation and you use CPAN
for updating Perl modules, then this software provides some
assistance to you.


- WHAT IS IT?

It is a wrapper for some of the CPAN modules' functions, namely
"r" (upgrade recommendations), "shell" and "install". These functions
are enriched with ChangeLog and BuildLog functionality. A new "history"
function allows you to look up when a modules' version has changed.
This aims at making module installation/upgrades more transparent
(ChangeLog) and easier to analyse in retrospect (BuildLog).

"r":        for every upgradeable module the corresponding ChangeLog
            entries are shown. This makes for an interesting read
            and helps you in deciding how urgent an upgrade for that
            module is.

"install":  provides a BuildLog for all of the output produced
            during install. Additionally, it creates an installation
            snapshot by calling "autobundle" after a successful
            install. Those snapshots help you to recreate the same
            module environment on another installation. Also,
            the "history" function uses them.
            A warning is issued if a modules' version number has not
            changed during upgrade, indicating a build problem.

"shell":    invokes the CPAN shell (CPAN::shell), while providing
	    a BuildLog of all output during the session. Upon exit,
            when there are changes in the installed modules, the
            ChangeLog database is updated and autobundle is called,
            similar to the non-interactive "install" mode.

"history":  looks for Snapshots and BuildLogs indicating that a
            module has been installed or where the install has failed


- WHY SHOULD I USE IT?

ChangeLogs can help you to find out when to 
  -avoid unnecessary work
            The ChangeLogs may tell you that the changes are not
            relevant to your installation, e.g. only for a specific
            OS you don't use or only add new functions you do not
            need, you might as well let your productive environment
            continue to run smoothly.
  -rush into action
            e.g. if it says SECURITY UPDATE


BuildLogs can help you to
  -use your precious time for other tasks while "install" is running
            You don't lose anything by not watching the build
            process "live" because you can look through the BuildLog
            later. Some modules may require keyboard input during
            install, though (e.g. CPAN, Mail::SpamAssassin).
  -reconstruct the history of a module
            You can see what answers were given to a modules' install
            questions, whether it had any build or test issues, even
            years after the fact. 
  -choose the right distribution file for downgrading
            Someone reports problems with the Foo module you have
            upgraded 4 times last month. Looks like you need do
            downgrade. But what version of the Foo module was
            installed before problems started?
            For downgrading you need to know its distribution file
            name, and the "history" function helps you find it.


- WHAT IT'S NOT

  -Prettiest code in the world
            This code will not stand up in a beauty contest. Tant pis.
            It's not intentionally ugly or obfuscated, but at least
            it is inconsistent style-wise.  Comments are in some
            places, not in others. Indentation is not in C-style.
            But even though it might not appeal to your senses you 
            can still put it to good use (hopefully).
      
  - The ultimate fully automatic and trouble-free CPAN updater(TM)
            CPAN and the CPAN module is nice and easy to use (after a
            while :-) But it's got a few deficiencies that are not
            completely remedied with this software.
            Here are two of them:
              -missing index of module versions to distribution files
                Most of the time you will just be installing the most
        	recent version and you do not need to worry. But if
                you want to revert to an older version of a module
                you have to know the distribution file to install.
 	           This software may provide help in guessing the
                   file from BuildLog and Snapshot information, but
	           having an authoritative list would be way better
             -after successful update, Perl may still use the
              old version of the module
               This happens when the CPAN version installs into a
               directory different from the previous version.  Only
               if you delete the old version the new version will
               become visible to Perl, and manually deleting files
               in a production system is a dangerous thing to do.
	       Examples: XSLoader, DBD::File
                   This software gives you a WARN if a modules
                   version has not changed in spite of having called
                   "-install" for it. But that does not help with
                   modules that CPAN has tried to install
                   automatically to resolve dependencies.