This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Use L<> rather than C<> in the Updated Modules section of perldelta.
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file. Any text flagged as
6 XXX needs to be processed before release. ]
7
8 perldelta - what is new for perl v5.15.0
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.15.0 release and
13 the 5.14.0 release.
14
15 If you are upgrading from an earlier release such as 5.YYY.YYY, first read
16 L<perl5YYYdelta>, which describes differences between 5.ZZZ.ZZZ and
17 5.YYY.YYY.
18
19 =head1 Notice
20
21 XXX Any important notices here
22
23 =head1 Core Enhancements
24
25 XXX New core language features go here. Summarise user-visible core language
26 enhancements. Particularly prominent performance optimisations could go
27 here, but most should go in the L</Performance Enhancements> section.
28
29 [ List each enhancement as a =head2 entry ]
30
31 =head1 Security
32
33 XXX Any security-related notices go here.  In particular, any security
34 vulnerabilities closed should be noted here rather than in the
35 L</Selected Bug Fixes> section.
36
37 [ List each security issue as a =head2 entry ]
38
39 =head1 Incompatible Changes
40
41 [ List each incompatible change as a =head2 entry ]
42
43 =head1 Deprecations
44
45 XXX Any deprecated features, syntax, modules etc. should be listed here.
46 In particular, deprecated modules should be listed here even if they are
47 listed as an updated module in the L</Modules and Pragmata> section.
48
49 [ List each deprecation as a =head2 entry ]
50
51 =head1 Performance Enhancements
52
53 XXX Changes which enhance performance without changing behaviour go here. There
54 may well be none in a stable release.
55
56 [ List each enhancement as a =item entry ]
57
58 =over 4
59
60 =item *
61
62 XXX
63
64 =back
65
66 =head1 Modules and Pragmata
67
68 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
69 go here.  If Module::CoreList is updated, generate an initial draft of the
70 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
71 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
72 below.  A paragraph summary for important changes should then be added by hand.
73 In an ideal world, dual-life modules would have a F<Changes> file that could be
74 cribbed.
75
76 [ Within each section, list entries as a =item entry ]
77
78 =head2 New Modules and Pragmata
79
80 =over 4
81
82 =item *
83
84 XXX
85
86 =back
87
88 =head2 Updated Modules and Pragmata
89
90 =over 4
91
92 =item *
93
94 L<Math::Complex> has been upgraded from version 1.56 to version 1.57.
95
96 Correct copy constructor usage.
97 Fix polarwise formatting with numeric format specifier.
98 More stable C<great_circle_direction> algorithm.
99
100 =item *
101
102 L<Time::HiRes> has been upgraded from version 1.9721_01 to version 1.9722.
103
104 Portability fix, and avoiding some compiler warnings.
105
106 =item *
107
108 XXX
109
110 =back
111
112 =head2 Removed Modules and Pragmata
113
114 =over 4
115
116 =item *
117
118 XXX
119
120 =back
121
122 =head1 Documentation
123
124 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
125 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
126
127 =head2 New Documentation
128
129 XXX Changes which create B<new> files in F<pod/> go here.
130
131 =head3 L<XXX>
132
133 XXX Description of the purpose of the new file here
134
135 =head2 Changes to Existing Documentation
136
137 XXX Changes which significantly change existing files in F<pod/> go here.
138 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
139 section.
140
141 =head3 L<XXX>
142
143 =over 4
144
145 =item *
146
147 XXX Description of the change here
148
149 =back
150
151 =head1 Diagnostics
152
153 The following additions or changes have been made to diagnostic output,
154 including warnings and fatal error messages.  For the complete list of
155 diagnostic messages, see L<perldiag>.
156
157 XXX New or changed warnings emitted by the core's C<C> code go here. Also
158 include any changes in L<perldiag> that reconcile it to the C<C> code.
159
160 [ Within each section, list entries as a =item entry ]
161
162 =head2 New Diagnostics
163
164 XXX Newly added diagnostic messages go here
165
166 =over 4
167
168 =item *
169
170 XXX
171
172 =back
173
174 =head2 Changes to Existing Diagnostics
175
176 XXX Changes (i.e. rewording) of diagnostic messages go here
177
178 =over 4
179
180 =item *
181
182 XXX
183
184 =back
185
186 =head1 Utility Changes
187
188 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
189 here. Most of these are built within the directories F<utils> and F<x2p>.
190
191 [ List utility changes as a =head3 entry for each utility and =item
192 entries for each change
193 Use L<XXX> with program names to get proper documentation linking. ]
194
195 =head3 L<XXX>
196
197 =over 4
198
199 =item *
200
201 XXX
202
203 =back
204
205 =head1 Configuration and Compilation
206
207 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
208 go here.  Any other changes to the Perl build process should be listed here.
209 However, any platform-specific changes should be listed in the
210 L</Platform Support> section, instead.
211
212 [ List changes as a =item entry ].
213
214 =over 4
215
216 =item *
217
218 XXX
219
220 =back
221
222 =head1 Testing
223
224 XXX Any significant changes to the testing of a freshly built perl should be
225 listed here.  Changes which create B<new> files in F<t/> go here as do any
226 large changes to the testing harness (e.g. when parallel testing was added).
227 Changes to existing files in F<t/> aren't worth summarising, although the bugs
228 that they represent may be covered elsewhere.
229
230 [ List each test improvement as a =item entry ]
231
232 =over 4
233
234 =item *
235
236 XXX
237
238 =back
239
240 =head1 Platform Support
241
242 XXX Any changes to platform support should be listed in the sections below.
243
244 [ Within the sections, list each platform as a =item entry with specific
245 changes as paragraphs below it. ]
246
247 =head2 New Platforms
248
249 XXX List any platforms that this version of perl compiles on, that previous
250 versions did not. These will either be enabled by new files in the F<hints/>
251 directories, or new subdirectories and F<README> files at the top level of the
252 source tree.
253
254 =over 4
255
256 =item XXX-some-platform
257
258 XXX
259
260 =back
261
262 =head2 Discontinued Platforms
263
264 XXX List any platforms that this version of perl no longer compiles on.
265
266 =over 4
267
268 =item XXX-some-platform
269
270 XXX
271
272 =back
273
274 =head2 Platform-Specific Notes
275
276 XXX List any changes for specific platforms. This could include configuration
277 and compilation changes or changes in portability/compatibility.  However,
278 changes within modules for platforms should generally be listed in the
279 L</Modules and Pragmata> section.
280
281 =over 4
282
283 =item XXX-some-platform
284
285 XXX
286
287 =back
288
289 =head1 Internal Changes
290
291 XXX Changes which affect the interface available to C<XS> code go here.
292 Other significant internal changes for future core maintainers should
293 be noted as well.
294
295 =over 4
296
297 =item *
298
299 The compiled representation of formats is now stored via the mg_ptr of
300 their PERL_MAGIC_fm. Previously it was stored in the string buffer,
301 beyond SvLEN(), the regular end of the string. SvCOMPILED() and
302 SvCOMPILED_{on,off}() now exist solely for compatibility for XS code.
303 The first is always 0, the other two now no-ops.
304
305 =back
306
307 =head1 Selected Bug Fixes
308
309 XXX Important bug fixes in the core language are summarised here.
310 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
311 L</Modules and Pragmata>.
312
313 [ List each fix as a =item entry ]
314
315 =over 4
316
317 =item *
318
319 XXX
320
321 =back
322
323 =head1 Known Problems
324
325 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
326 tests that had to be C<TODO>ed for the release would be noted here, unless
327 they were specific to a particular platform (see below).
328
329 This is a list of some significant unfixed bugs, which are regressions
330 from either 5.XXX.XXX or 5.XXX.XXX.
331
332 [ List each fix as a =item entry ]
333
334 =over 4
335
336 =item *
337
338 XXX
339
340 =back
341
342 =head1 Obituary
343
344 XXX If any significant core contributor has died, we've added a short obituary
345 here.
346
347 =head1 Acknowledgements
348
349 XXX The list of people to thank goes here.
350
351 =head1 Reporting Bugs
352
353 If you find what you think is a bug, you might check the articles
354 recently posted to the comp.lang.perl.misc newsgroup and the perl
355 bug database at http://rt.perl.org/perlbug/ .  There may also be
356 information at http://www.perl.org/ , the Perl Home Page.
357
358 If you believe you have an unreported bug, please run the L<perlbug>
359 program included with your release.  Be sure to trim your bug down
360 to a tiny but sufficient test case.  Your bug report, along with the
361 output of C<perl -V>, will be sent off to perlbug@perl.org to be
362 analysed by the Perl porting team.
363
364 If the bug you are reporting has security implications, which make it
365 inappropriate to send to a publicly archived mailing list, then please send
366 it to perl5-security-report@perl.org. This points to a closed subscription
367 unarchived mailing list, which includes all the core committers, who be able
368 to help assess the impact of issues, figure out a resolution, and help
369 co-ordinate the release of patches to mitigate or fix the problem across all
370 platforms on which Perl is supported. Please only use this address for
371 security issues in the Perl core, not for modules independently
372 distributed on CPAN.
373
374 =head1 SEE ALSO
375
376 The F<Changes> file for an explanation of how to view exhaustive details
377 on what changed.
378
379 The F<INSTALL> file for how to build Perl.
380
381 The F<README> file for general stuff.
382
383 The F<Artistic> and F<Copying> files for copyright information.
384
385 =cut