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.04
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.03 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. Note: The "T" marker
38       before the time portion is optional.
39
40       In order to satisfy release events not made to the public, or dates
41       that are historically unknown, the following strings are also
42       available:
43
44       •   Unknown Release Date
45
46       •   Unknown
47
48       •   Not Released
49
50       •   Development Release
51
52       •   Development
53
54       •   Developer Release
55

STRUCTURE

57   Required Elements
58       In its simplest form, the only required elements are a "Version", a
59       "Date" and the noted changes. Blank lines between the "Version" line
60       and the first "Change" line are optional. Blank lines between "Change"
61       lines are also optional.
62
63           <Version>(whitespace/non-"word" characters)<Date>
64           (whitespace)<Change>
65
66       NOTE: The characters between a "Version" and a "Date" must start with
67       whitespace, but may subsquently contain any combination of whitespace
68       and non-"word" characters. Example:
69
70           0.01 - 2013-12-11
71
72       "Change" lines have no specific format. Commonly, authors will use a
73       dash "-" followed by a space to start a new change, and indent
74       subsequent lines for multi-line changes. Example
75
76           - Simple Change
77           - This is a very very very long
78             change line
79
80       Although there is no limit on line length, authors generally wrap each
81       line at 78 columns.
82
83   Optional Elements
84       Release Note
85
86       Any text following the "Date" portion of the "Version" line will be
87       considered the "Release Note". Example:
88
89           0.01 2013-04-01 Codename: April Fool
90
91             - First Release
92
93   Preamble
94       Any amount of text before the first "Version" line will be considered
95       part of the preamble. Most existing distributions include something
96       along the lines of:
97
98           Revision history for perl module My::Module
99
100       Or
101
102           Revision history for perl distribution My-Distribution
103
104   Groups
105       Changelog entries may be grouped under headings. Heading lines begin
106       with an opening square bracket ("["), and end with a matching square
107       bracket ("]").  When parsing group headings, leading and trailing
108       whitespace inside the brackets should be discarded.
109
110           (whitespace)[Grouping Name]
111           (whitespace)<Change>
112
113       Since empty lines hold no special meaning, all "Change" lines will fall
114       under the current group until a new group heading is found. Example:
115
116           [ First Group ]
117           - First Change
118
119           - Second Change; in first group
120
121           [ Second Group ]
122           - First Change; in second group
123

EXAMPLES

125   Basic Example
126           0.01 2009-07-16
127            - Initial release
128
129   Example with a preamble
130           Revision history for perl module Foo::Bar
131
132           0.02 2009-07-17
133
134            - Added more foo() tests
135
136           0.01 2009-07-16
137
138            - Initial release
139
140   Example with groups
141           Revision history for perl module Foo::Bar
142
143           0.03 2009-07-18
144
145            [Important Security Information]
146            - This release fixes critical bug RT #1234
147
148            [Other Changes]
149            - Added some feature
150
151           0.02 2009-07-17
152
153            - Added more foo() tests
154
155           0.01 2009-07-16T19:20:30+01:00
156
157            - Initial release
158

SEE ALSO

160       •   CPAN::Changes
161
162       •   Test::CPAN::Changes
163

AUTHOR

165       Brian Cassidy <bricas@cpan.org>
166

168       Copyright 2011-2013 by Brian Cassidy
169
170       This is free software; you can redistribute it and/or modify it under
171       the same terms as Perl itself.
172
173
174
175perl v5.36.0                      2023-01-20            CPAN::Changes::Spec(3)
Impressum