
=pod

=head1 NAME

CPAN::Changes::Spec - Specification for CPAN Changes files

=head1 VERSION

version 0.01

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

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

=head1 STRUCTURE

=head2 Required Elements

In its simplest form, the only required elements are a version, a 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)<Date>
    (whitespace)<Change>

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

=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

=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-2012 by Brian Cassidy

This is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. 

=cut
