Commit | Line | Data |
---|---|---|
3d6c5fec DG |
1 | =head1 NAME |
2 | ||
3 | how_to_write_a_perldelta - How to write a perldelta | |
4 | ||
5 | =head2 Description | |
20a4c497 NC |
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 | |
919671d7 | 10 | to do something, see if it's been done before, and if the approach works |
b56e599f RL |
11 | there, steal it. (L<perl5300delta> and L<perl5320delta> are both quite |
12 | lengthy and contain good examples for many of the perldelta sections.) | |
20a4c497 | 13 | |
b56e599f | 14 | =head2 Template Automation |
57b3b745 | 15 | |
b56e599f RL |
16 | Note that F<Porting/perldelta_template.pod> contains a skeleton version of |
17 | a perldelta.pod file. Following the steps in the Release Manager's Guide | |
18 | (F<Porting/release_managers_guide.pod>) usually ensures hassle-free | |
19 | rotation of the most recently completed perldelta.pod and preparation of | |
20 | a fresh new document ready for the next release. | |
21 | ||
22 | The skeleton document also contains inline hints on how to prepare the | |
23 | final perldelta.pod. (These hints should be removed in turn as each section | |
24 | of the final perldelta.pod is completed.) | |
57b3b745 | 25 | |
20a4c497 NC |
26 | =head2 Style |
27 | ||
28 | Pod is more a physical markup language, rather than a logical markup language. | |
29 | Despite that it has some built in conventions. B<Stick to them>: | |
30 | ||
31 | =over 4 | |
32 | ||
33 | =item * C<FE<lt>E<gt>> is for File | |
34 | ||
35 | =item * C<CE<lt>E<gt>> is for Code | |
36 | ||
37 | =item * C<LE<lt>E<gt>> is for Link | |
38 | ||
39 | =back | |
40 | ||
41 | Whilst modules could also be links, usually in the context of the perldelta | |
42 | the reference is to code C<use>ing them, rather than something within their | |
43 | documentation. | |
44 | ||
45 | Be consistent in how bugs are referenced. One style is | |
46 | ||
47 | =over 4 | |
48 | ||
b56e599f RL |
49 | =item GitHub |
50 | ||
51 | C<[GH #12345]> can be used to reference both Issues and Pull Requests. | |
52 | ||
5cfe25fd DG |
53 | =item rt.cpan.org |
54 | ||
55 | C<rt.cpan.org #43010> inline, but enclose in square brackets after a sentence. | |
56 | C<[rt.cpan.org #43010]>. This mirrors how rt.cpan.org subject lines appear. | |
20a4c497 NC |
57 | |
58 | =item ActiveState | |
59 | ||
4b05bc8e | 60 | C<L<http://bugs.activestate.com/show_bug.cgi?id=72443>> |
20a4c497 NC |
61 | |
62 | =item Debian | |
63 | ||
64 | C<Debian bug #379463> | |
65 | ||
66 | =back | |
67 | ||
68 | =head2 Copy editing | |
69 | ||
70 | Be consistent. | |
71 | ||
72 | In a list, either make every item a note, or a full sentence. Either end | |
f337e982 NC |
73 | every item with a full stop, or ensure that no item ends with one. I<regex> |
74 | B<xor> I<regexp> - choose exactly one, and stick to it. | |
20a4c497 NC |
75 | |
76 | =head2 Sections | |
77 | ||
78 | Historically, the perldelta has consisted of a sequence of C<=head1> | |
79 | sections, usually in the same order. Un-needed sections are deleted, | |
80 | and if something doesn't fit nicely into the existing sections, a new | |
81 | more appropriate section is created. | |
82 | ||
83 | =over | |
84 | ||
85 | =item NAME | |
86 | ||
87 | Follows this formula: | |
88 | ||
89 | perl5104delta - what is new for perl v5.10.4 | |
90 | ||
91 | =item DESCRIPTION | |
92 | ||
93 | For a release on a stable branch, follows this formula: | |
94 | ||
555bd962 BG |
95 | This document describes differences between the 5.10.3 release |
96 | and the 5.10.4 release. | |
20a4c497 NC |
97 | |
98 | For the start of a new stable branch, follows this formula: | |
99 | ||
14074713 KE |
100 | This document describes differences between the 5.10.0 release |
101 | and the 5.12.0 release. | |
20a4c497 | 102 | |
b56e599f RL |
103 | This clearly sets the scope of which changes are to be summarized in the |
104 | rest of the document. | |
105 | ||
106 | For all releases, a second paragraph points to the previous perldelta: | |
107 | ||
108 | If you are upgrading from an earlier release such as 5.rXXX.aXXX, | |
109 | first read perl5XXXdelta, which describes differences between | |
110 | 5.rXXX.aXXX and 5.sXXX.bXXX. | |
20a4c497 NC |
111 | |
112 | =item Notice | |
113 | ||
114 | There was a I<Notice> section in L<perl589delta>, to carry an important | |
115 | notice. | |
116 | ||
b56e599f RL |
117 | =item Core Enhancements |
118 | ||
119 | New core language features go here. Summarize user-visible core language | |
120 | enhancements. Particularly prominent performance optimisations could go | |
121 | here, but most should go in the L</Performance Enhancements> section. | |
122 | ||
123 | Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata> | |
124 | ||
125 | =item Security | |
126 | ||
127 | Any security-related notices go here. In particular, any security | |
128 | vulnerabilities closed should be noted here rather than in the | |
129 | "Selected Bug Fixes" section. | |
130 | ||
131 | L<perl5303delta> has multiple such examples, as well as | |
132 | a useful accompanying paragraph outlining the known attack | |
133 | vectors / requirements for the vulnerabilities to be exploitable. | |
134 | ||
20a4c497 NC |
135 | =item Incompatible Changes |
136 | ||
137 | For a release on a stable branch, this section aspires to be | |
138 | ||
555bd962 BG |
139 | There are no changes intentionally incompatible with 5.10.3. |
140 | If any exist, they are bugs and reports are welcome. | |
20a4c497 | 141 | |
b56e599f | 142 | Otherwise, changes should be listed as =head2 entries. |
20a4c497 | 143 | |
b56e599f | 144 | =item Deprecations |
20a4c497 | 145 | |
b56e599f | 146 | Add any new known deprecations (features, syntax, modules) here. |
20a4c497 | 147 | |
b56e599f RL |
148 | A I<Module removals> subsection can be used to foreshadow planned removal |
149 | of core modules in a future release. Modules that were actually removed | |
150 | in this release should go in the "Modules and Pragmata" section. | |
20a4c497 | 151 | |
b56e599f RL |
152 | =item Performance Enhancements |
153 | ||
154 | Changes which enhance performance without changing behaviour go here. There | |
155 | may well be none in a stable release. | |
20a4c497 NC |
156 | |
157 | =item Modules and Pragmata | |
158 | ||
2c5d738b SH |
159 | All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/> go |
160 | here, in a list ordered by distribution name. Minimally it should be the | |
161 | module version, but it's more useful to the end user to give a paragraph's | |
162 | summary of the module's changes. In an ideal world, dual-life modules would | |
163 | have a F<Changes> file that could be cribbed. | |
20a4c497 NC |
164 | |
165 | Whilst this section could be built by incrementally working through change | |
166 | descriptions applying to files, this is prone to error. It's better to | |
b56e599f | 167 | collate changes by module, and then summarize all changes to a module as a |
2c5d738b | 168 | group. |
0be987a2 | 169 | |
60984f2f | 170 | If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl> |
2c5d738b | 171 | will automatically update two sections in F<perldelta>: |
88e14305 DG |
172 | |
173 | * New Modules and Pragmata | |
2c5d738b | 174 | * Updated Modules and Pragmata |
b56e599f | 175 | * Removed Modules and Pragmata |
88e14305 DG |
176 | |
177 | Each section will have stub entries following a template like this: | |
0be987a2 | 178 | |
60984f2f | 179 | =item C<less> |
0be987a2 | 180 | |
60984f2f | 181 | Upgraded from version 0.01 to 0.02 |
0be987a2 | 182 | |
88e14305 | 183 | It does not include modules listed in F<Porting/Maintainers.pl> under |
47e01c32 | 184 | C<_PERLLIB>, but it's a start. Where relevant, a summary of changes can be |
88e14305 | 185 | added by hand. |
0be987a2 | 186 | |
60984f2f | 187 | A more adventurous enhancement would be to automate grabbing |
0be987a2 NC |
188 | the changelogs for dual lived modules. For each of them, grab the relevant |
189 | changes files from CPAN for the old and new versions, and if the old one is | |
b56e599f | 190 | a strict subset of the new one, use the extra lines as a basis for summarizing. |
0be987a2 NC |
191 | |
192 | (And if not, experiment with using F<git> to get the relevant part of changelog | |
2c5d738b | 193 | for the particular file in core.) |
0be987a2 | 194 | |
20a4c497 NC |
195 | =item New Documentation |
196 | ||
197 | Changes which create B<new> files in F<pod/> go here. | |
198 | ||
0be987a2 NC |
199 | B<FIXME> - this could be automated, at least as far as generating a first |
200 | draft. | |
201 | ||
202 | =over | |
203 | ||
204 | =item 1 | |
205 | ||
206 | Start with a clean exploded tarball of the previous release, and a clean | |
207 | checkout of the branch in question | |
208 | ||
209 | =item 2 | |
210 | ||
211 | Take the F<MANIFEST> file of each | |
212 | ||
213 | =item 3 | |
214 | ||
215 | Search for lines matching C<m!^pod/.*\.pod!> | |
216 | ||
217 | =item 4 | |
218 | ||
219 | Diff them | |
220 | ||
221 | =item 5 | |
222 | ||
223 | Explode if anyone deleted documentation. [No idea what the policy on that is | |
224 | yet] | |
225 | ||
226 | =item 6 | |
227 | ||
228 | For each file only in the newer F<MANIFEST> | |
229 | ||
230 | =over | |
231 | ||
60984f2f | 232 | =item 1 |
0be987a2 NC |
233 | |
234 | Use F<git> to determine its Author | |
235 | ||
236 | =item 2 | |
237 | ||
238 | Open the pod file itself | |
239 | ||
240 | =item 3 | |
241 | ||
242 | Grab the description section | |
243 | ||
244 | =item 4 | |
245 | ||
246 | Write out a block of text starting roughly | |
247 | ||
248 | L<perlfoo>, by A. U. Thor, provides @description | |
249 | ||
250 | =back | |
251 | ||
252 | =back | |
253 | ||
20a4c497 NC |
254 | =item Changes to Existing Documentation |
255 | ||
256 | Changes which significantly change existing files in F<pod/> go here. | |
257 | Any changes to F<pod/perldiag.pod> should go in | |
b56e599f | 258 | L</New Diagnostics> or L</Changed Diagnostics>. |
20a4c497 | 259 | |
b56e599f | 260 | =item New Diagnostics |
20a4c497 | 261 | |
b56e599f | 262 | New warnings emitted by the core's C<C> code go here. |
20a4c497 | 263 | |
b56e599f | 264 | =item Changed Diagnostics |
20a4c497 | 265 | |
b56e599f | 266 | Changed warnings emitted by the core's C<C> code go here. |
20a4c497 | 267 | |
b56e599f | 268 | =item Utility Changes |
20a4c497 | 269 | |
b56e599f RL |
270 | Changes to installed programs such as F<perldoc> and F<xsubpp> go here. Most |
271 | of these are built within the directory F<utils>. | |
20a4c497 | 272 | |
b56e599f | 273 | =item Configuration and Compilation |
20a4c497 | 274 | |
b56e599f RL |
275 | Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools |
276 | go here. | |
20a4c497 | 277 | |
b56e599f | 278 | =item Testing |
20a4c497 NC |
279 | |
280 | Changes which create B<new> files in F<t/> go here. Changes to existing files | |
b56e599f | 281 | in F<t/> aren't worth summarizing, although the bugs that they represent |
20a4c497 NC |
282 | may be. |
283 | ||
f95a4791 | 284 | Autogenerate this section by running something like this: |
0be987a2 | 285 | |
f95a4791 | 286 | # perl newtests-perldelta.pl v5.11.1 HEAD |
0be987a2 | 287 | |
b56e599f RL |
288 | =item Platform Support |
289 | ||
290 | Any changes specific to a particular platform. VMS and Win32 are the usual | |
291 | stars here. It's probably best to group changes under the same section layout | |
292 | as the main perldelta. | |
293 | ||
294 | =item New Platforms | |
295 | ||
296 | List any platforms that this version of perl compiles on, that previous | |
297 | versions did not. These will either be enabled by new files in the F<hints/> | |
298 | directories, or new subdirectories and F<README> files at the top level of the | |
299 | source tree. | |
300 | ||
301 | =item Discontinued Platforms | |
302 | ||
303 | List any platforms that this version of perl no longer compiles on. The | |
304 | reverse of the advice above applies - look for removed hints or README files. | |
305 | ||
306 | =item Platform-Specific Notes | |
307 | ||
308 | Changes of note to specific platforms go here. | |
309 | ||
310 | =item Internal Changes | |
311 | ||
312 | Changes which affect the interface available to C<XS> code go here. | |
313 | ||
314 | =item Selected Bug Fixes | |
315 | ||
316 | Important bug fixes in the core language are summarized here. | |
317 | Bug fixes in files in F<ext/> and F<lib/> are best summarized in | |
318 | L</Modules and Pragmata>. | |
319 | ||
20a4c497 NC |
320 | =item Known Problems |
321 | ||
322 | Descriptions of platform agnostic bugs we know we can't fix go here. Any | |
323 | tests that had to be C<TODO>ed for the release would be noted here, unless | |
324 | they were specific to a particular platform (see below). | |
325 | ||
b56e599f | 326 | =item Errata From Previous Releases |
87b6d269 | 327 | |
b56e599f | 328 | XXXXXXXXXX TODO |
20a4c497 NC |
329 | |
330 | =item Obituary | |
331 | ||
332 | If any significant core contributor has died, we've added a short obituary | |
333 | here. | |
334 | ||
335 | =item Acknowledgements | |
336 | ||
548e9a3a | 337 | Generate this with: |
20a4c497 | 338 | |
548e9a3a | 339 | perl Porting/acknowledgements.pl v5.15.0..HEAD |
a59108e8 | 340 | |
20a4c497 NC |
341 | =item Reporting Bugs |
342 | ||
343 | This doesn't usually need to be changed from the previous perldelta. | |
344 | ||
b56e599f RL |
345 | =item Give Thanks |
346 | ||
347 | This doesn't usually need to be changed from the previous perldelta. | |
348 | ||
20a4c497 NC |
349 | =item SEE ALSO |
350 | ||
351 | This doesn't usually need to be changed from the previous perldelta. | |
352 | ||
353 | =back |