.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPAN::Changes::Spec 3pm"
.TH CPAN::Changes::Spec 3pm "2013-12-11" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CPAN::Changes::Spec \- Specification for CPAN Changes files
.SH "VERSION"
.IX Header "VERSION"
version 0.04
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    Revision history for perl module Foo::Bar
\&
\&    0.02 2009\-07\-17
\&
\&     \- Added more foo() tests
\&
\&    0.01 2009\-07\-16
\&
\&     \- Initial release
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document describes version 0.03 of the specification for Changes files
included in a \s-1CPAN\s0 distribution.
.PP
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.
.SH "DATA TYPES"
.IX Header "DATA TYPES"
.SS "Version"
.IX Subsection "Version"
Versions should be formatted as described in \*(L"Version-Formats\*(R" in CPAN::Meta::Spec.
.SS "Date"
.IX Subsection "Date"
A date/time in the format specified by <http://www.w3.org/TR/NOTE\-datetime> 
aka W3CDTF. \fBNote:\fR The \*(L"T\*(R" marker before the time portion is optional.
.PP
In order to satisfy release events not made to the public, or dates 
that are historically unknown, the following strings are also available:
.IP "\(bu" 4
Unknown Release Date
.IP "\(bu" 4
Unknown
.IP "\(bu" 4
Not Released
.IP "\(bu" 4
Development Release
.IP "\(bu" 4
Development
.IP "\(bu" 4
Developer Release
.SH "STRUCTURE"
.IX Header "STRUCTURE"
.SS "Required Elements"
.IX Subsection "Required Elements"
In its simplest form, the only required elements are a \f(CW\*(C`Version\*(C'\fR, a \f(CW\*(C`Date\*(C'\fR and
the noted changes. Blank lines between the \f(CW\*(C`Version\*(C'\fR line and the first 
\&\f(CW\*(C`Change\*(C'\fR line are optional. Blank lines between \f(CW\*(C`Change\*(C'\fR lines are also
optional.
.PP
.Vb 2
\&    <Version>(whitespace/non\-"word" characters)<Date>
\&    (whitespace)<Change>
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR The characters between a \f(CW\*(C`Version\*(C'\fR and a \f(CW\*(C`Date\*(C'\fR must start with 
whitespace, but may subsquently contain any combination of whitespace and 
non\-\*(L"word\*(R" characters. Example:
.PP
.Vb 1
\&    0.01 \- 2013\-12\-11
.Ve
.PP
\&\f(CW\*(C`Change\*(C'\fR lines have no specific format. Commonly, authors will use a dash
\&\f(CW\*(C`\-\*(C'\fR followed by a space to start a new change, and indent subsequent lines
for multi-line changes. Example
.PP
.Vb 3
\&    \- Simple Change
\&    \- This is a very very very long
\&      change line
.Ve
.PP
Although there is no limit on line length, authors generally wrap each line 
at 78 columns.
.SS "Optional Elements"
.IX Subsection "Optional Elements"
\fIRelease Note\fR
.IX Subsection "Release Note"
.PP
Any text following the \f(CW\*(C`Date\*(C'\fR portion of the \f(CW\*(C`Version\*(C'\fR line will be 
considered the \f(CW\*(C`Release Note\*(C'\fR. Example:
.PP
.Vb 1
\&    0.01 2013\-04\-01 Codename: April Fool
\&    
\&      \- First Release
.Ve
.SS "Preamble"
.IX Subsection "Preamble"
Any amount of text before the first \f(CW\*(C`Version\*(C'\fR line will be considered part 
of the preamble. Most existing distributions include something along the
lines of:
.PP
.Vb 1
\&    Revision history for perl module My::Module
.Ve
.PP
Or
.PP
.Vb 1
\&    Revision history for perl distribution My\-Distribution
.Ve
.SS "Groups"
.IX Subsection "Groups"
Changelog entries may be grouped under headings. Heading lines begin with an
opening square bracket (\f(CW\*(C`[\*(C'\fR), and end with a matching square bracket (\f(CW\*(C`]\*(C'\fR). 
When parsing group headings, leading and trailing whitespace inside the 
brackets should be discarded.
.PP
.Vb 2
\&    (whitespace)[Grouping Name]
\&    (whitespace)<Change>
.Ve
.PP
Since empty lines hold no special meaning, all \f(CW\*(C`Change\*(C'\fR lines will fall 
under the current group until a new group heading is found. Example:
.PP
.Vb 2
\&    [ First Group ]
\&    \- First Change
\&    
\&    \- Second Change; in first group
\&
\&    [ Second Group ]
\&    \- First Change; in second group
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Basic Example"
.IX Subsection "Basic Example"
.Vb 2
\&    0.01 2009\-07\-16
\&     \- Initial release
.Ve
.SS "Example with a preamble"
.IX Subsection "Example with a preamble"
.Vb 1
\&    Revision history for perl module Foo::Bar
\&
\&    0.02 2009\-07\-17
\&
\&     \- Added more foo() tests
\&
\&    0.01 2009\-07\-16
\&
\&     \- Initial release
.Ve
.SS "Example with groups"
.IX Subsection "Example with groups"
.Vb 1
\&    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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
CPAN::Changes
.IP "\(bu" 4
Test::CPAN::Changes
.SH "AUTHOR"
.IX Header "AUTHOR"
Brian Cassidy <bricas@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2011\-2013 by Brian Cassidy
.PP
This is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.