1CPAN::Changes::Spec(3)User Contributed Perl DocumentationCPAN::Changes::Spec(3)
2
3
4

NAME

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

VERSION

9       version 0.01
10

SYNOPSIS

12           Revision history for perl module Foo::Bar
13
14           0.02 2009-07-17
15
16            - Added more foo() tests
17
18           0.01 2009-07-16
19
20            - Initial release
21

DESCRIPTION

23       This document describes version 0.1 of the specification for Changes
24       files included in a CPAN distribution.
25
26       It is intended as a guide for module authors to encourage them to write
27       meaningful changelogs as well as provide a programmatic interface to
28       reliably read and write Changes files.
29

DATA TYPES

31   Version
32       Versions should be formatted as described in "Version_Formats" in
33       CPAN::Meta::Spec.
34
35   Date
36       A date/time in the format specified by
37       http://www.w3.org/TR/NOTE-datetime <http://www.w3.org/TR/NOTE-datetime>
38       aka W3CDTF.
39

STRUCTURE

41   Required Elements
42       In its simplest form, the only required elements are a version, a date
43       and the noted changes. Blank lines between the "Version" line and the
44       first "Change" line are optional. Blank lines between "Change" lines
45       are also optional.
46
47           <Version>(whitespace)<Date>
48           (whitespace)<Change>
49
50       "Change" lines have no specific format. Commonly, authors will use a
51       dash "-" followed by a space to start a new change, and indent
52       subsequent lines for multi-line changes. Example
53
54           - Simple Change
55           - This is a very very very long
56             change line
57
58   Preamble
59       Any amount of text before the first "Version" line will be considered
60       part of the preamble. Most existing distributions include something
61       along the lines of:
62
63           Revision history for perl module My::Module
64
65   Groups
66       Changelog entries may be grouped under headings. Heading lines begin
67       with an opening square bracket ("["), and end with a matching square
68       bracket ("]").  When parsing group headings, leading and trailing
69       whitespace inside the brackets should be discarded.
70
71           (whitespace)[Grouping Name]
72           (whitespace)<Change>
73
74       Since empty lines hold no special meaning, all "Change" lines will fall
75       under the current group until a new group heading is found. Example:
76
77           [ First Group ]
78           - First Change
79
80           - Second Change; in first group
81
82           [ Second Group ]
83           - First Change; in second group
84

EXAMPLES

86   Basic Example
87           0.01 2009-07-16
88            - Initial release
89
90   Example with a preamble
91           Revision history for perl module Foo::Bar
92
93           0.02 2009-07-17
94
95            - Added more foo() tests
96
97           0.01 2009-07-16
98
99            - Initial release
100
101   Example with groups
102           Revision history for perl module Foo::Bar
103
104           0.03 2009-07-18
105
106            [Important Security Information]
107            - This release fixes critical bug RT #1234
108
109            [Other Changes]
110            - Added some feature
111
112           0.02 2009-07-17
113
114            - Added more foo() tests
115
116           0.01 2009-07-16T19:20:30+01:00
117
118            - Initial release
119

SEE ALSO

121       ·   CPAN::Changes
122
123       ·   Test::CPAN::Changes
124

AUTHOR

126       Brian Cassidy <bricas@cpan.org>
127

129       Copyright 2011 by Brian Cassidy
130
131       This is free software; you can redistribute it and/or modify it under
132       the same terms as Perl itself.
133
134
135
136perl v5.12.3                      2011-02-02            CPAN::Changes::Spec(3)
Impressum