Commit | Line | Data |
---|---|---|
20a4c497 NC |
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 | ||
57b3b745 DM |
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 | ||
20a4c497 NC |
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 | |
f337e982 NC |
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. | |
20a4c497 NC |
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 | ||
68346ec5 | 88 | Clearly this sets the scope of which changes are to be summarised in the rest |
20a4c497 NC |
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 | ||
0be987a2 NC |
132 | B<FIXME> - this could be automated, although the two below would be easier |
133 | to start with. | |
134 | ||
135 | Start with F<Porting/cmpVERSION.pl> | |
136 | ||
137 | Augment it with a flag, so that instead of reporting which modules are | |
138 | different but have the same version, report on modules which I<are> different. | |
139 | Grab the old version from the exploded tarball, and the new version from | |
140 | the git checkout, and output the line | |
141 | ||
142 | =item * | |
143 | ||
144 | C<less> upgraded from version 0.01 to 0.02 | |
145 | ||
146 | That's a start. | |
147 | ||
148 | Once that's done, a more adventurous enhancement is to automate grabbing | |
149 | the changelogs for dual lived modules. For each of them, grab the relevant | |
150 | changes files from CPAN for the old and new versions, and if the old one is | |
151 | a strict subset of the new one, splice the extra lines right into the output, | |
152 | as a basis for summarising. | |
153 | ||
154 | (And if not, experiment with using F<git> to get the relevant part of changelog | |
155 | for the particular file in core) | |
156 | ||
157 | These could also be enhanced further by using a Pod parser module to produce | |
158 | a parse tree of F<perl${whatever}delta.pod>, and splicing in the updates | |
159 | correctly without throwing existing entries away. | |
160 | ||
161 | If you think that's nuts, take a look at what F<pod/buildtoc> already does to | |
162 | splice into existing Makefiles on various platforms: | |
163 | ||
164 | http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498 | |
165 | ||
166 | Perl is this really powerful language for text manipulation. And fun to | |
167 | play with. We need to get that message out. :-) | |
168 | ||
20a4c497 NC |
169 | =item Utility Changes |
170 | ||
171 | Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most | |
172 | of these are built within the directories F<utils> and F<x2p>. | |
173 | ||
174 | =item New Documentation | |
175 | ||
176 | Changes which create B<new> files in F<pod/> go here. | |
177 | ||
0be987a2 NC |
178 | B<FIXME> - this could be automated, at least as far as generating a first |
179 | draft. | |
180 | ||
181 | =over | |
182 | ||
183 | =item 1 | |
184 | ||
185 | Start with a clean exploded tarball of the previous release, and a clean | |
186 | checkout of the branch in question | |
187 | ||
188 | =item 2 | |
189 | ||
190 | Take the F<MANIFEST> file of each | |
191 | ||
192 | =item 3 | |
193 | ||
194 | Search for lines matching C<m!^pod/.*\.pod!> | |
195 | ||
196 | =item 4 | |
197 | ||
198 | Diff them | |
199 | ||
200 | =item 5 | |
201 | ||
202 | Explode if anyone deleted documentation. [No idea what the policy on that is | |
203 | yet] | |
204 | ||
205 | =item 6 | |
206 | ||
207 | For each file only in the newer F<MANIFEST> | |
208 | ||
209 | =over | |
210 | ||
211 | =item 1 | |
212 | ||
213 | Use F<git> to determine its Author | |
214 | ||
215 | =item 2 | |
216 | ||
217 | Open the pod file itself | |
218 | ||
219 | =item 3 | |
220 | ||
221 | Grab the description section | |
222 | ||
223 | =item 4 | |
224 | ||
225 | Write 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 | ||
235 | Changes which significantly change existing files in F<pod/> go here. | |
236 | Any changes to F<pod/perldiag.pod> should go in | |
237 | L</New or Changed Diagnostics>. | |
238 | ||
239 | =item Performance Enhancements | |
240 | ||
241 | Changes which enhance performance without changing behaviour go here. There | |
242 | may well be none in a stable release. | |
243 | ||
244 | =item Installation and Configuration Improvements | |
245 | ||
246 | Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools | |
247 | go here. | |
248 | ||
249 | =item Selected Bug Fixes | |
250 | ||
251 | Important bug fixes in the core language are summarised here. | |
252 | Bug fixes in files in F<ext/> and F<lib/> are best summarised in | |
253 | L</Modules and Pragmata>. | |
254 | ||
255 | =item New or Changed Diagnostics | |
256 | ||
257 | New or changed warnings emitted by the core's C<C> code go here. | |
258 | ||
259 | =item Changed Internals | |
260 | ||
261 | Changes which affect the interface available to C<XS> code go here. | |
262 | ||
263 | =item New Tests | |
264 | ||
265 | Changes which create B<new> files in F<t/> go here. Changes to existing files | |
266 | in F<t/> aren't worth summarising, although the bugs that they represent | |
267 | may be. | |
268 | ||
0be987a2 NC |
269 | B<FIXME> - this could be automated, at least as far as generating a first |
270 | draft. | |
271 | ||
272 | =over | |
273 | ||
274 | =item 1 | |
275 | ||
276 | Start with a clean exploded tarball of the previous release, and a clean | |
277 | checkout of the branch in question | |
278 | ||
279 | =item 2 | |
280 | ||
281 | Take the F<MANIFEST> file of each | |
282 | ||
283 | =item 3 | |
284 | ||
285 | Search for lines matching C<m!t/.*\.t!> (and I think also for new tests in | |
286 | F<ext/DynaLoader>) | |
287 | ||
288 | =item 4 | |
289 | ||
290 | Diff them | |
291 | ||
292 | =item 5 | |
293 | ||
294 | For each file only in the newer F<MANIFEST> | |
295 | ||
296 | =over | |
297 | ||
298 | =item 1 | |
299 | ||
300 | Grab the description line from F<MANIFEST> | |
301 | ||
302 | =item 2 | |
303 | ||
304 | Write out an =item section with the filename, and description, just like | |
305 | L<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 | ||
313 | Descriptions of platform agnostic bugs we know we can't fix go here. Any | |
314 | tests that had to be C<TODO>ed for the release would be noted here, unless | |
315 | they were specific to a particular platform (see below). | |
316 | ||
87b6d269 DM |
317 | =item Deprecations |
318 | ||
319 | Add any new known deprecations here. | |
320 | ||
20a4c497 NC |
321 | =item Platform Specific Notes |
322 | ||
323 | Any changes specific to a particular platform. VMS and Win32 are the usual | |
324 | stars here. It's probably best to group changes under the same section layout | |
325 | as the main perldelta. | |
326 | ||
327 | =item Obituary | |
328 | ||
329 | If any significant core contributor has died, we've added a short obituary | |
330 | here. | |
331 | ||
332 | =item Acknowledgements | |
333 | ||
334 | The list of people to thank goes here. | |
335 | ||
336 | =item Reporting Bugs | |
337 | ||
338 | This doesn't usually need to be changed from the previous perldelta. | |
339 | ||
340 | =item SEE ALSO | |
341 | ||
342 | This doesn't usually need to be changed from the previous perldelta. | |
343 | ||
344 | =back |