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> aka W3CDTF.
38

STRUCTURE

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

EXAMPLES

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

SEE ALSO

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

AUTHOR

125       Brian Cassidy <bricas@cpan.org>
126

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