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

       Brian Cassidy <bricas@cpan.org>

       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.

perl v5.40.1                                       2025-04-20                           CPAN::Changes::Spec(3pm)

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

       •   Unknown Release Date

       •   Unknown

       •   Not Released

       •   Development Release

       •   Development

       •   Developer Release

       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.

BasicExample
           0.01 2009-07-16
            - Initial release

   Examplewithapreamble
           Revision history for perl module Foo::Bar

           0.02 2009-07-17

            - Added more foo() tests

           0.01 2009-07-16

            - Initial release

   Examplewithgroups
           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

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

       •   CPAN::Changes

       •   Test::CPAN::Changes

RequiredElements
       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/non-"word" characters)<Date>
           (whitespace)<Change>

       NOTE:  The  characters  between a "Version" and a "Date" must start with whitespace, but may subsequently
       contain any combination of whitespace and non-"word" characters. Example:

           0.01 - 2013-12-11

       "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

       Although there is no limit on line length, authors generally wrap each line at 78 columns.

   OptionalElementsReleaseNote

       Any  text  following  the  "Date"  portion  of  the "Version" line will be considered the "Release Note".
       Example:

           0.01 2013-04-01 Codename: April Fool

             - First Release

   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

       Or

           Revision history for perl distribution My-Distribution

   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

           Revision history for perl module Foo::Bar

           0.02 2009-07-17

            - Added more foo() tests

           0.01 2009-07-16

            - Initial release

       version 0.500005