Commit | Line | Data |
20a4c497 |
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 |
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 |
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 |
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 |
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 |
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 | |
60984f2f |
132 | B<FIXME> - this could be automated better |
0be987a2 |
133 | |
60984f2f |
134 | If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl> |
88e14305 |
135 | will automatically print out several sections if relevent that can be |
136 | pasted into F<perldelta>: |
137 | |
138 | * New Modules and Pragmata |
139 | * Pragmata Changes |
140 | * Updated Modules |
141 | * Removed Modules and Pragmata |
142 | |
143 | Each section will have stub entries following a template like this: |
0be987a2 |
144 | |
60984f2f |
145 | =item C<less> |
0be987a2 |
146 | |
60984f2f |
147 | Upgraded from version 0.01 to 0.02 |
0be987a2 |
148 | |
88e14305 |
149 | It does not include modules listed in F<Porting/Maintainers.pl> under |
150 | C<_PERLLIB>, but it's a start. Where relevent, a summary of changes can be |
151 | added by hand. |
0be987a2 |
152 | |
60984f2f |
153 | A more adventurous enhancement would be to automate grabbing |
0be987a2 |
154 | the changelogs for dual lived modules. For each of them, grab the relevant |
155 | changes files from CPAN for the old and new versions, and if the old one is |
156 | a strict subset of the new one, splice the extra lines right into the output, |
157 | as a basis for summarising. |
158 | |
159 | (And if not, experiment with using F<git> to get the relevant part of changelog |
160 | for the particular file in core) |
161 | |
162 | These could also be enhanced further by using a Pod parser module to produce |
163 | a parse tree of F<perl${whatever}delta.pod>, and splicing in the updates |
164 | correctly without throwing existing entries away. |
165 | |
166 | If you think that's nuts, take a look at what F<pod/buildtoc> already does to |
167 | splice into existing Makefiles on various platforms: |
168 | |
169 | http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498 |
170 | |
171 | Perl is this really powerful language for text manipulation. And fun to |
172 | play with. We need to get that message out. :-) |
173 | |
20a4c497 |
174 | =item Utility Changes |
175 | |
176 | Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most |
177 | of these are built within the directories F<utils> and F<x2p>. |
178 | |
179 | =item New Documentation |
180 | |
181 | Changes which create B<new> files in F<pod/> go here. |
182 | |
0be987a2 |
183 | B<FIXME> - this could be automated, at least as far as generating a first |
184 | draft. |
185 | |
186 | =over |
187 | |
188 | =item 1 |
189 | |
190 | Start with a clean exploded tarball of the previous release, and a clean |
191 | checkout of the branch in question |
192 | |
193 | =item 2 |
194 | |
195 | Take the F<MANIFEST> file of each |
196 | |
197 | =item 3 |
198 | |
199 | Search for lines matching C<m!^pod/.*\.pod!> |
200 | |
201 | =item 4 |
202 | |
203 | Diff them |
204 | |
205 | =item 5 |
206 | |
207 | Explode if anyone deleted documentation. [No idea what the policy on that is |
208 | yet] |
209 | |
210 | =item 6 |
211 | |
212 | For each file only in the newer F<MANIFEST> |
213 | |
214 | =over |
215 | |
60984f2f |
216 | =item 1 |
0be987a2 |
217 | |
218 | Use F<git> to determine its Author |
219 | |
220 | =item 2 |
221 | |
222 | Open the pod file itself |
223 | |
224 | =item 3 |
225 | |
226 | Grab the description section |
227 | |
228 | =item 4 |
229 | |
230 | Write out a block of text starting roughly |
231 | |
232 | L<perlfoo>, by A. U. Thor, provides @description |
233 | |
234 | =back |
235 | |
236 | =back |
237 | |
20a4c497 |
238 | =item Changes to Existing Documentation |
239 | |
240 | Changes which significantly change existing files in F<pod/> go here. |
241 | Any changes to F<pod/perldiag.pod> should go in |
242 | L</New or Changed Diagnostics>. |
243 | |
244 | =item Performance Enhancements |
245 | |
246 | Changes which enhance performance without changing behaviour go here. There |
247 | may well be none in a stable release. |
248 | |
249 | =item Installation and Configuration Improvements |
250 | |
251 | Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools |
252 | go here. |
253 | |
254 | =item Selected Bug Fixes |
255 | |
256 | Important bug fixes in the core language are summarised here. |
257 | Bug fixes in files in F<ext/> and F<lib/> are best summarised in |
258 | L</Modules and Pragmata>. |
259 | |
260 | =item New or Changed Diagnostics |
261 | |
262 | New or changed warnings emitted by the core's C<C> code go here. |
263 | |
264 | =item Changed Internals |
265 | |
266 | Changes which affect the interface available to C<XS> code go here. |
267 | |
268 | =item New Tests |
269 | |
270 | Changes which create B<new> files in F<t/> go here. Changes to existing files |
271 | in F<t/> aren't worth summarising, although the bugs that they represent |
272 | may be. |
273 | |
f95a4791 |
274 | Autogenerate this section by running something like this: |
0be987a2 |
275 | |
f95a4791 |
276 | # perl newtests-perldelta.pl v5.11.1 HEAD |
0be987a2 |
277 | |
20a4c497 |
278 | =item Known Problems |
279 | |
280 | Descriptions of platform agnostic bugs we know we can't fix go here. Any |
281 | tests that had to be C<TODO>ed for the release would be noted here, unless |
282 | they were specific to a particular platform (see below). |
283 | |
87b6d269 |
284 | =item Deprecations |
285 | |
286 | Add any new known deprecations here. |
287 | |
20a4c497 |
288 | =item Platform Specific Notes |
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 Obituary |
295 | |
296 | If any significant core contributor has died, we've added a short obituary |
297 | here. |
298 | |
299 | =item Acknowledgements |
300 | |
301 | The list of people to thank goes here. |
302 | |
a59108e8 |
303 | You can find the list of committers and authors by: |
304 | |
208edbfe |
305 | % git log --pretty='format:%an' v5.11.1..HEAD | sort | uniq |
a59108e8 |
306 | |
307 | And how many files where changed by: |
308 | |
208edbfe |
309 | % git diff --stat=200,200 v5.11.1..HEAD |
a59108e8 |
310 | |
20a4c497 |
311 | =item Reporting Bugs |
312 | |
313 | This doesn't usually need to be changed from the previous perldelta. |
314 | |
315 | =item SEE ALSO |
316 | |
317 | This doesn't usually need to be changed from the previous perldelta. |
318 | |
319 | =back |