This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add a guide to writing a perldelta.
[perl5.git] / Porting / how_to_write_a_perldelta.pod
CommitLineData
20a4c497
NC
1=head1 How to write a perldelta
2
3This is intended as a guide for how to write a perldelta. There has never
4been a formal specification - the working rule is "fake up a document that
5looks something close to the existing perldeltas". So if it's unclear how
6do to do something, see if it's been done before, and if the approach works
7there, steal it.
8
9=head2 Style
10
11Pod is more a physical markup language, rather than a logical markup language.
12Despite that it has some built in conventions. B<Stick to them>:
13
14=over 4
15
16=item * C<FE<lt>E<gt>> is for File
17
18=item * C<CE<lt>E<gt>> is for Code
19
20=item * C<LE<lt>E<gt>> is for Link
21
22=back
23
24Whilst modules could also be links, usually in the context of the perldelta
25the reference is to code C<use>ing them, rather than something within their
26documentation.
27
28Be consistent in how bugs are referenced. One style is
29
30=over 4
31
32=item rt.perl.org
33
34C<RT #43010> inline, but enclose in square brackets after a sentence.
35C<[RT #43010]>
36
37=item ActiveState
38
39C<http://bugs.activestate.com/show_bug.cgi?id=72443>
40
41=item Debian
42
43C<Debian bug #379463>
44
45=back
46
47=head2 Copy editing
48
49Be consistent.
50
51In a list, either make every item a note, or a full sentence. Either end
52every item with a full stop, or ensure that no item ends with one.
53
54=head2 Sections
55
56Historically, the perldelta has consisted of a sequence of C<=head1>
57sections, usually in the same order. Un-needed sections are deleted,
58and if something doesn't fit nicely into the existing sections, a new
59more appropriate section is created.
60
61=over
62
63=item NAME
64
65Follows this formula:
66
67 perl5104delta - what is new for perl v5.10.4
68
69=item DESCRIPTION
70
71For a release on a stable branch, follows this formula:
72
73 This document describes differences between the 5.10.3 release and
74 the 5.10.4 release.
75
76For the start of a new stable branch, follows this formula:
77
78 This document describes differences between the 5.12.0 release and
79 the 5.10.0 release.
80
81Clearly this sets the scope of which changes are to be summarise in the rest
82of the document.
83
84=item Notice
85
86There was a I<Notice> section in L<perl589delta>, to carry an important
87notice.
88
89=item Incompatible Changes
90
91For a release on a stable branch, this section aspires to be
92
93 There are no changes intentionally incompatible with 5.10.3. If any exist,
94 they are bugs and reports are welcome.
95
96=item Core Enhancements
97
98New core language features go here. Summarise user-visible core language
99enhancements. Particularly prominent performance optimisations could go
100here, but most should go in the L</Performance Enhancements> section.
101
102Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
103
104=item New Platforms
105
106List any platforms that this version of perl compiles on, that previous
107versions did not. These will either be enabled by new files in the F<hints/>
108directories, or new subdirectories and F<README> files at the top level of the
109source tree.
110
111=item Modules and Pragmata
112
113All changes to installed files in F<ext/> and F<lib/> go here, in a list
114ordered by distribution name. Minimally it should be the module version,
115but it's more useful to the end user to give a paragraph's summary of the
116module's changes. In an ideal world, dual-life modules would have a
117F<Changes> file that could be cribbed.
118
119Whilst this section could be built by incrementally working through change
120descriptions applying to files, this is prone to error. It's better to
121collate changes to F<ext/> and F<lib/> by module, and then summarise all
122changes to a module as a group. This can be done by partitioning directories
123within F<ext/> and F<lib/> to a number of people.
124
125=item Utility Changes
126
127Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
128of these are built within the directories F<utils> and F<x2p>.
129
130=item New Documentation
131
132Changes which create B<new> files in F<pod/> go here.
133
134=item Changes to Existing Documentation
135
136Changes which significantly change existing files in F<pod/> go here.
137Any changes to F<pod/perldiag.pod> should go in
138L</New or Changed Diagnostics>.
139
140=item Performance Enhancements
141
142Changes which enhance performance without changing behaviour go here. There
143may well be none in a stable release.
144
145=item Installation and Configuration Improvements
146
147Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
148go here.
149
150=item Selected Bug Fixes
151
152Important bug fixes in the core language are summarised here.
153Bug fixes in files in F<ext/> and F<lib/> are best summarised in
154L</Modules and Pragmata>.
155
156=item New or Changed Diagnostics
157
158New or changed warnings emitted by the core's C<C> code go here.
159
160=item Changed Internals
161
162Changes which affect the interface available to C<XS> code go here.
163
164=item New Tests
165
166Changes which create B<new> files in F<t/> go here. Changes to existing files
167in F<t/> aren't worth summarising, although the bugs that they represent
168may be.
169
170=item Known Problems
171
172Descriptions of platform agnostic bugs we know we can't fix go here. Any
173tests that had to be C<TODO>ed for the release would be noted here, unless
174they were specific to a particular platform (see below).
175
176=item Platform Specific Notes
177
178Any changes specific to a particular platform. VMS and Win32 are the usual
179stars here. It's probably best to group changes under the same section layout
180as the main perldelta.
181
182=item Obituary
183
184If any significant core contributor has died, we've added a short obituary
185here.
186
187=item Acknowledgements
188
189The list of people to thank goes here.
190
191=item Reporting Bugs
192
193This doesn't usually need to be changed from the previous perldelta.
194
195=item SEE ALSO
196
197This doesn't usually need to be changed from the previous perldelta.
198
199=back