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