(perl #131836) avoid a use-after-free after parsing a "sub" keyword
[perl.git] / Porting / how_to_write_a_perldelta.pod
1 =head1 NAME
2
3 how_to_write_a_perldelta - How to write a perldelta
4
5 =head2 Description
6
7 This is intended as a guide for how to write a perldelta. There has never
8 been a formal specification - the working rule is "fake up a document that
9 looks something close to the existing perldeltas". So if it's unclear how
10 to do something, see if it's been done before, and if the approach works
11 there, steal it.
12
13 =head2 Template
14
15 Note there is a file F<Porting/perldelta_template.pod> which contains a
16 skeleton version of a perldelta.pod file, which should normally be copied
17 in at the start of a new release.
18
19 =head2 Style
20
21 Pod is more a physical markup language, rather than a logical markup language.
22 Despite that it has some built in conventions. B<Stick to them>:
23
24 =over 4
25
26 =item * C<FE<lt>E<gt>> is for File
27
28 =item * C<CE<lt>E<gt>> is for Code
29
30 =item * C<LE<lt>E<gt>> is for Link
31
32 =back
33
34 Whilst modules could also be links, usually in the context of the perldelta
35 the reference is to code C<use>ing them, rather than something within their
36 documentation.
37
38 Be consistent in how bugs are referenced. One style is
39
40 =over 4
41
42 =item rt.perl.org
43
44 C<perl #43010> inline, but enclose in square brackets after a sentence.
45 C<[perl #43010]>.  This mirrors how rt.perl.org subject lines appear.
46
47 =item rt.cpan.org
48
49 C<rt.cpan.org #43010> inline, but enclose in square brackets after a sentence.
50 C<[rt.cpan.org #43010]>.  This mirrors how rt.cpan.org subject lines appear.
51
52 =item ActiveState
53
54 C<L<http://bugs.activestate.com/show_bug.cgi?id=72443>>
55
56 =item Debian
57
58 C<Debian bug #379463>
59
60 =back
61
62 =head2 Copy editing
63
64 Be consistent.
65
66 In a list, either make every item a note, or a full sentence. Either end
67 every item with a full stop, or ensure that no item ends with one. I<regex>
68 B<xor> I<regexp> - choose exactly one, and stick to it.
69
70 =head2 Sections
71
72 Historically, the perldelta has consisted of a sequence of C<=head1>
73 sections, usually in the same order. Un-needed sections are deleted,
74 and if something doesn't fit nicely into the existing sections, a new
75 more appropriate section is created.
76
77 =over
78
79 =item NAME
80
81 Follows this formula:
82
83     perl5104delta - what is new for perl v5.10.4
84
85 =item DESCRIPTION
86
87 For a release on a stable branch, follows this formula:
88
89     This document describes differences between the 5.10.3 release
90     and the 5.10.4 release.
91
92 For the start of a new stable branch, follows this formula:
93
94     This document describes differences between the 5.12.0 release
95     and the 5.10.0 release.
96
97 Clearly this sets the scope of which changes are to be summarised in the rest
98 of the document.
99
100 =item Notice
101
102 There was a I<Notice> section in L<perl589delta>, to carry an important
103 notice.
104
105 =item Incompatible Changes
106
107 For a release on a stable branch, this section aspires to be
108
109     There are no changes intentionally incompatible with 5.10.3.
110     If any exist, they are bugs and reports are welcome.
111
112 =item Core Enhancements
113
114 New core language features go here. Summarise user-visible core language
115 enhancements. Particularly prominent performance optimisations could go
116 here, but most should go in the L</Performance Enhancements> section.
117
118 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
119
120 =item New Platforms
121
122 List any platforms that this version of perl compiles on, that previous
123 versions did not. These will either be enabled by new files in the F<hints/>
124 directories, or new subdirectories and F<README> files at the top level of the
125 source tree.
126
127 =item Modules and Pragmata
128
129 All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/> go
130 here, in a list ordered by distribution name. Minimally it should be the
131 module version, but it's more useful to the end user to give a paragraph's
132 summary of the module's changes. In an ideal world, dual-life modules would
133 have a F<Changes> file that could be cribbed.
134
135 Whilst this section could be built by incrementally working through change
136 descriptions applying to files, this is prone to error. It's better to
137 collate changes by module, and then summarise all changes to a module as a
138 group.
139
140 If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
141 will automatically update two sections in F<perldelta>:
142
143     * New Modules and Pragmata
144     * Updated Modules and Pragmata
145
146 (Currently, it does not update the Removed Modules and Pragmata section.)
147
148 Each section will have stub entries following a template like this:
149
150     =item C<less>
151
152     Upgraded from version 0.01 to 0.02
153
154 It does not include modules listed in F<Porting/Maintainers.pl> under
155 C<_PERLLIB>, but it's a start.  Where relevant, a summary of changes can be
156 added by hand.
157
158 A more adventurous enhancement would be to automate grabbing
159 the changelogs for dual lived modules. For each of them, grab the relevant
160 changes files from CPAN for the old and new versions, and if the old one is
161 a strict subset of the new one, use the extra lines as a basis for summarising.
162
163 (And if not, experiment with using F<git> to get the relevant part of changelog
164 for the particular file in core.)
165
166 =item Utility Changes
167
168 Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
169 of these are built within the directory F<utils>.
170
171 =item New Documentation
172
173 Changes which create B<new> files in F<pod/> go here.
174
175 B<FIXME> - this could be automated, at least as far as generating a first
176 draft.
177
178 =over
179
180 =item 1
181
182 Start with a clean exploded tarball of the previous release, and a clean
183 checkout of the branch in question
184
185 =item 2
186
187 Take the F<MANIFEST> file of each
188
189 =item 3
190
191 Search for lines matching C<m!^pod/.*\.pod!>
192
193 =item 4
194
195 Diff them
196
197 =item 5
198
199 Explode if anyone deleted documentation. [No idea what the policy on that is
200 yet]
201
202 =item 6
203
204 For each file only in the newer F<MANIFEST>
205
206 =over
207
208 =item 1
209
210 Use F<git> to determine its Author
211
212 =item 2
213
214 Open the pod file itself
215
216 =item 3
217
218 Grab the description section
219
220 =item 4
221
222 Write out a block of text starting roughly
223
224     L<perlfoo>, by A. U. Thor, provides @description
225
226 =back
227
228 =back
229
230 =item Changes to Existing Documentation
231
232 Changes which significantly change existing files in F<pod/> go here.
233 Any changes to F<pod/perldiag.pod> should go in
234 L</New or Changed Diagnostics>.
235
236 =item Performance Enhancements
237
238 Changes which enhance performance without changing behaviour go here. There
239 may well be none in a stable release.
240
241 =item Installation and Configuration Improvements
242
243 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
244 go here.
245
246 =item Selected Bug Fixes
247
248 Important bug fixes in the core language are summarised here.
249 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
250 L</Modules and Pragmata>.
251
252 =item New or Changed Diagnostics
253
254 New or changed warnings emitted by the core's C<C> code go here.
255
256 =item Changed Internals
257
258 Changes which affect the interface available to C<XS> code go here.
259
260 =item New Tests
261
262 Changes which create B<new> files in F<t/> go here. Changes to existing files
263 in F<t/> aren't worth summarising, although the bugs that they represent
264 may be.
265
266 Autogenerate this section by running something like this:
267
268  # perl newtests-perldelta.pl v5.11.1 HEAD
269
270 =item Known Problems
271
272 Descriptions of platform agnostic bugs we know we can't fix go here. Any
273 tests that had to be C<TODO>ed for the release would be noted here, unless
274 they were specific to a particular platform (see below).
275
276 =item Deprecations
277
278 Add any new known deprecations here.
279
280 =item Platform Specific Notes
281
282 Any changes specific to a particular platform. VMS and Win32 are the usual
283 stars here. It's probably best to group changes under the same section layout
284 as the main perldelta.
285
286 =item Obituary
287
288 If any significant core contributor has died, we've added a short obituary
289 here.
290
291 =item Acknowledgements
292
293 Generate this with:
294
295   perl Porting/acknowledgements.pl v5.15.0..HEAD
296
297 =item Reporting Bugs
298
299 This doesn't usually need to be changed from the previous perldelta.
300
301 =item SEE ALSO
302
303 This doesn't usually need to be changed from the previous perldelta.
304
305 =back