CPAN::Changes::Spec(3) User Contributed Perl Documentation CPAN::Changes::Spec(3)
NAME
CPAN::Changes::Spec - Specification for CPAN Changes files
VERSION
version 0.01
SYNOPSIS
Revision history for perl module Foo::Bar
0.02 2009-07-17
- Added more foo() tests
0.01 2009-07-16
- Initial release
DESCRIPTION
This document describes version 0.1 of the specification for Changes files included in a CPAN distribution.
It is intended as a guide for module authors to encourage them to write meaningful changelogs as well as provide a programmatic interface
to reliably read and write Changes files.
DATA TYPES
Version
Versions should be formatted as described in "Version-Formats" in CPAN::Meta::Spec.
Date
A date/time in the format specified by <http://www.w3.org/TR/NOTE-datetime> aka W3CDTF.
STRUCTURE
Required Elements
In its simplest form, the only required elements are a version, a date and the noted changes. Blank lines between the "Version" line and
the first "Change" line are optional. Blank lines between "Change" lines are also optional.
<Version>(whitespace)<Date>
(whitespace)<Change>
"Change" lines have no specific format. Commonly, authors will use a dash "-" followed by a space to start a new change, and indent
subsequent lines for multi-line changes. Example
- Simple Change
- This is a very very very long
change line
Preamble
Any amount of text before the first "Version" line will be considered part of the preamble. Most existing distributions include something
along the lines of:
Revision history for perl module My::Module
Groups
Changelog entries may be grouped under headings. Heading lines begin with an opening square bracket ("["), and end with a matching square
bracket ("]"). When parsing group headings, leading and trailing whitespace inside the brackets should be discarded.
(whitespace)[Grouping Name]
(whitespace)<Change>
Since empty lines hold no special meaning, all "Change" lines will fall under the current group until a new group heading is found.
Example:
[ First Group ]
- First Change
- Second Change; in first group
[ Second Group ]
- First Change; in second group
EXAMPLES
Basic Example
0.01 2009-07-16
- Initial release
Example with a preamble
Revision history for perl module Foo::Bar
0.02 2009-07-17
- Added more foo() tests
0.01 2009-07-16
- Initial release
Example with groups
Revision history for perl module Foo::Bar
0.03 2009-07-18
[Important Security Information]
- This release fixes critical bug RT #1234
[Other Changes]
- Added some feature
0.02 2009-07-17
- Added more foo() tests
0.01 2009-07-16T19:20:30+01:00
- Initial release
SEE ALSO
o CPAN::Changes
o Test::CPAN::Changes
AUTHOR
Brian Cassidy <bricas@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2011-2012 by Brian Cassidy
This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl v5.16.3 2012-04-30 CPAN::Changes::Spec(3)