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