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