ProPeler
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
perl5
/
CPAN
/
Changes
/
Filename :
Spec.pod
back
Copy
=pod =head1 NAME CPAN::Changes::Spec - Specification for CPAN Changes files =head1 VERSION version 0.04 =head1 SYNOPSIS Revision history for perl module Foo::Bar 0.02 2009-07-17 - Added more foo() tests 0.01 2009-07-16 - Initial release =head1 DESCRIPTION This document describes version 0.03 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. =head1 DATA TYPES =head2 Version Versions should be formatted as described in L<CPAN::Meta::Spec/Version-Formats>. =head2 Date A date/time in the format specified by L<http://www.w3.org/TR/NOTE-datetime> aka W3CDTF. B<Note:> The "T" marker before the time portion is optional. In order to satisfy release events not made to the public, or dates that are historically unknown, the following strings are also available: =over 4 =item * Unknown Release Date =item * Unknown =item * Not Released =item * Development Release =item * Development =item * Developer Release =back =head1 STRUCTURE =head2 Required Elements In its simplest form, the only required elements are a C<Version>, a C<Date> and the noted changes. Blank lines between the C<Version> line and the first C<Change> line are optional. Blank lines between C<Change> lines are also optional. <Version>(whitespace/non-"word" characters)<Date> (whitespace)<Change> B<NOTE:> The characters between a C<Version> and a C<Date> must start with whitespace, but may subsquently contain any combination of whitespace and non-"word" characters. Example: 0.01 - 2013-12-11 C<Change> lines have no specific format. Commonly, authors will use a dash C<-> 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 Although there is no limit on line length, authors generally wrap each line at 78 columns. =head2 Optional Elements =head3 Release Note Any text following the C<Date> portion of the C<Version> line will be considered the C<Release Note>. Example: 0.01 2013-04-01 Codename: April Fool - First Release =head2 Preamble Any amount of text before the first C<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 Or Revision history for perl distribution My-Distribution =head2 Groups Changelog entries may be grouped under headings. Heading lines begin with an opening square bracket (C<[>), and end with a matching square bracket (C<]>). 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 C<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 =head1 EXAMPLES =head2 Basic Example 0.01 2009-07-16 - Initial release =head2 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 =head2 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 =head1 SEE ALSO =over 4 =item * L<CPAN::Changes> =item * L<Test::CPAN::Changes> =back =head1 AUTHOR Brian Cassidy E<lt>bricas@cpan.orgE<gt> =head1 COPYRIGHT AND LICENSE Copyright 2011-2013 by Brian Cassidy This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut