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