view release on metacpan or  search on metacpan

README  view on Meta::CPAN

Acme-CreatingCPANModules

The README is used to introduce the module and provide instructions on
how to install the module, any machine dependencies it may have (for
example C compilers and installed libraries) and any other information
that should be provided before the module is installed.

A README file is required for CPAN modules since CPAN extracts the README
file from a module distribution so that people browsing the archive
can use it get an idea of the modules uses. It is usually a good idea
to provide version information here so that people can decide whether
fixes for the module are worth downloading.

INSTALLATION

To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

lib/Acme/CreatingCPANModules.pm  view on Meta::CPAN

And then there's the Changes file, where you're supposed to write down
the changes you made to your module each new version.

Let's look at the files in detail.

[slide] Here's a Changes file.

Note that the order of the changes is chronologically inversed. Why?
Because the purporse of a changes file is (among others) to let the
user know what you changed from the last version, so that he can
decide if he wants to install your module.

Hence, and since browsers and editors usually open files in their
beginning, it's only reasonable that you put the most recent changes
on the top of the file.

As for what you put in here, it's kind of up to you, but you don't
need to be too technical. If you added some tests, just say "added
some tests". You don't really need to specify which ones and the
purpose of each of them.