This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 5f8324b
[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 XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.21.3
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.21.2 release and the 5.21.3
13 release.
14
15 If you are upgrading from an earlier release such as 5.21.1, first read
16 L<perl5212delta>, which describes differences between 5.21.1 and 5.21.2.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head1 Security
31
32 XXX Any security-related notices go here.  In particular, any security
33 vulnerabilities closed should be noted here rather than in the
34 L</Selected Bug Fixes> section.
35
36 [ List each security issue as a =head2 entry ]
37
38 =head1 Incompatible Changes
39
40 XXX For a release on a stable branch, this section aspires to be:
41
42     There are no changes intentionally incompatible with 5.XXX.XXX
43     If any exist, they are bugs, and we request that you submit a
44     report.  See L</Reporting Bugs> below.
45
46 [ List each incompatible change as a =head2 entry ]
47
48 =head2 S<C<use UNIVERSAL '...'>> is now a fatal error
49
50 Importing functions from C<UNIVERSAL> has been deprecated since v5.12, and
51 is now a fatal error.  S<C<"use UNIVERSAL">> without any arguments is still
52 allowed.
53
54 =head1 Deprecations
55
56 XXX Any deprecated features, syntax, modules etc. should be listed here.
57
58 =head2 Module removals
59
60 XXX Remove this section if inapplicable.
61
62 The following modules will be removed from the core distribution in a
63 future release, and will at that time need to be installed from CPAN.
64 Distributions on CPAN which require these modules will need to list them as
65 prerequisites.
66
67 The core versions of these modules will now issue C<"deprecated">-category
68 warnings to alert you to this fact.  To silence these deprecation warnings,
69 install the modules in question from CPAN.
70
71 Note that these are (with rare exceptions) fine modules that you are encouraged
72 to continue to use.  Their disinclusion from core primarily hinges on their
73 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
74 not usually on concerns over their design.
75
76 =over
77
78 =item XXX
79
80 XXX Note that deprecated modules should be listed here even if they are listed
81 as an updated module in the L</Modules and Pragmata> section.
82
83 =back
84
85 [ List each other deprecation as a =head2 entry ]
86
87 =head1 Performance Enhancements
88
89 XXX Changes which enhance performance without changing behaviour go here.
90 There may well be none in a stable release.
91
92 [ List each enhancement as a =item entry ]
93
94 =over 4
95
96 =item *
97
98 XXX
99
100 =back
101
102 =head1 Modules and Pragmata
103
104 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
105 go here.  If Module::CoreList is updated, generate an initial draft of the
106 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
107 for important changes should then be added by hand.  In an ideal world,
108 dual-life modules would have a F<Changes> file that could be cribbed.
109
110 [ Within each section, list entries as a =item entry ]
111
112 =head2 New Modules and Pragmata
113
114 =over 4
115
116 =item *
117
118 XXX
119
120 =back
121
122 =head2 Updated Modules and Pragmata
123
124 =over 4
125
126 =item *
127
128 L<B::Debug> has been upgraded from version 1.19 to 1.21
129
130 =item *
131
132 L<CPAN::Meta> has been upgraded from version 2.141520 to 2.142060.
133
134 =item *
135
136 L<CPAN::Meta::Requirements> has been upgraded from version 2.125 to 2.126.
137
138 =item *
139
140 L<ExtUtils::Manifest> has been upgraded from version 1.64 to 1.65.
141
142 The MANIFEST is now opened with C<:raw>, to prevent C<CRLF>s leaking in.
143
144 =item *
145
146 L<perl5db.pl> has been upgraded from version 1.45 to 1.46.
147
148 Fixed the scope level handling of the debugger's C<y> command.
149
150 =item *
151
152 L<POSIX> has been upgraded from version 1.41 to 1.42.
153
154 Replaced the thread-unsafe code used to prevent duplicate warning
155 messages for using the isxxx() functions.  [perl #122476]
156
157 =item *
158
159 L<Socket> has been upgraded from version 2.014 to 2.015.
160
161 Test suite updates, particularly useful for Solaris and cygwin, and
162 a slight change to the pattern used for IPv4 address matching.
163
164 =back
165
166 =head2 Removed Modules and Pragmata
167
168 =over 4
169
170 =item *
171
172 XXX
173
174 =back
175
176 =head1 Documentation
177
178 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
179 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
180
181 =head2 New Documentation
182
183 XXX Changes which create B<new> files in F<pod/> go here.
184
185 =head3 L<XXX>
186
187 XXX Description of the purpose of the new file here
188
189 =head2 Changes to Existing Documentation
190
191 XXX Changes which significantly change existing files in F<pod/> go here.
192 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
193 section.
194
195 =head3 L<XXX>
196
197 =over 4
198
199 =item *
200
201 XXX Description of the change here
202
203 =back
204
205 =head1 Diagnostics
206
207 The following additions or changes have been made to diagnostic output,
208 including warnings and fatal error messages.  For the complete list of
209 diagnostic messages, see L<perldiag>.
210
211 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
212 include any changes in L<perldiag> that reconcile it to the C<C> code.
213
214 =head2 New Diagnostics
215
216 XXX Newly added diagnostic messages go under here, separated into New Errors
217 and New Warnings
218
219 =head3 New Errors
220
221 =over 4
222
223 =item *
224
225 XXX L<message|perldiag/"message">
226
227 =back
228
229 =head3 New Warnings
230
231 =over 4
232
233 =item *
234
235 L<Hexadecimal float: exponent overflow|perldiag/"Hexadecimal float: exponent overflow">
236
237 (W overflow) The hexadecimal floating point has larger exponent
238 than the floating point supports.
239
240 =item *
241
242 L<Hexadecimal float: exponent underflow|perldiag/"Hexadecimal float: exponent underflow">
243
244 (W overflow) The hexadecimal floating point has smaller exponent
245 than the floating point supports.
246
247 =item *
248
249 L<Hexadecimal float: internal error|perldiag/"Hexadecimal float: internal error">
250
251 (F) Something went horribly bad in hexadecimal float handling.
252
253 =item *
254
255 L<Hexadecimal float: mantissa overflow|perldiag/"Hexadecimal float: mantissa overflow">
256
257 (W overflow) The hexadecimal floating point literal had more bits in
258 the mantissa (the part between the 0x and the exponent, also known as
259 the fraction or the significand) than the floating point supports.
260
261 =item *
262
263 L<Hexadecimal float: precision loss|perldiag/"Hexadecimal float: precision loss">
264
265 (W overflow) The hexadecimal floating point had internally more
266 digits than could be output.  This can be caused by unsupported
267 long double formats, or by 64-bit integers not being available
268 (needed to retrieve the digits under some configurations).
269
270 =item *
271
272 L<Hexadecimal float: unsupported long double format|perldiag/"Hexadecimal float: unsupported long double format">
273
274 (F) You have configured Perl to use long doubles but
275 the internals of the long double format are unknown,
276 therefore the hexadecimal float output is impossible.
277
278 =back
279
280 =head2 Changes to Existing Diagnostics
281
282 XXX Changes (i.e. rewording) of diagnostic messages go here
283
284 =over 4
285
286 =item *
287
288 XXX Describe change here
289
290 =back
291
292 =head1 Utility Changes
293
294 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
295 Most of these are built within the directory F<utils>.
296
297 [ List utility changes as a =head2 entry for each utility and =item
298 entries for each change
299 Use L<XXX> with program names to get proper documentation linking. ]
300
301 =head2 L<XXX>
302
303 =over 4
304
305 =item *
306
307 XXX
308
309 =back
310
311 =head1 Configuration and Compilation
312
313 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
314 go here.  Any other changes to the Perl build process should be listed here.
315 However, any platform-specific changes should be listed in the
316 L</Platform Support> section, instead.
317
318 [ List changes as a =item entry ].
319
320 =over 4
321
322 =item *
323
324 Internal handling of floating point values has been improved.
325
326 =back
327
328 =head1 Testing
329
330 XXX Any significant changes to the testing of a freshly built perl should be
331 listed here.  Changes which create B<new> files in F<t/> go here as do any
332 large changes to the testing harness (e.g. when parallel testing was added).
333 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
334 that they represent may be covered elsewhere.
335
336 [ List each test improvement as a =item entry ]
337
338 =over 4
339
340 =item *
341
342 XXX
343
344 =back
345
346 =head1 Platform Support
347
348 XXX Any changes to platform support should be listed in the sections below.
349
350 [ Within the sections, list each platform as a =item entry with specific
351 changes as paragraphs below it. ]
352
353 =head2 New Platforms
354
355 XXX List any platforms that this version of perl compiles on, that previous
356 versions did not.  These will either be enabled by new files in the F<hints/>
357 directories, or new subdirectories and F<README> files at the top level of the
358 source tree.
359
360 =over 4
361
362 =item XXX-some-platform
363
364 XXX
365
366 =back
367
368 =head2 Discontinued Platforms
369
370 XXX List any platforms that this version of perl no longer compiles on.
371
372 =over 4
373
374 =item XXX-some-platform
375
376 XXX
377
378 =back
379
380 =head2 Platform-Specific Notes
381
382 XXX List any changes for specific platforms.  This could include configuration
383 and compilation changes or changes in portability/compatibility.  However,
384 changes within modules for platforms should generally be listed in the
385 L</Modules and Pragmata> section.
386
387 =over 4
388
389 =item XXX-some-platform
390
391 XXX
392
393 =back
394
395 =head1 Internal Changes
396
397 XXX Changes which affect the interface available to C<XS> code go here.  Other
398 significant internal changes for future core maintainers should be noted as
399 well.
400
401 [ List each change as a =item entry ]
402
403 =over 4
404
405 =item *
406
407 Added L<perlapi/sync_locale>.
408 Changing the program's locale should be avoided by XS code.  Nevertheless,
409 certain non-Perl libraries called from XS, such as C<Gtk> do so.  When this
410 happens, Perl needs to be told that the locale has changed.  Use this function
411 to do so, before returning to Perl.
412
413 =back
414
415 =head1 Selected Bug Fixes
416
417 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
418 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
419
420 [ List each fix as a =item entry ]
421
422 =over 4
423
424 =item *
425
426 Failing to compile C<use Foo> in an eval could leave a spurious
427 C<BEGIN> subroutine definition, which would produce a "Subroutine
428 BEGIN redefined" warning on the next use of C<use>, or other C<BEGIN>
429 block.  [perl #122107]
430
431 =item *
432
433 C<method { BLOCK } ARGS> syntax now correctly parses the arguments if they
434 begin with an opening brace.  [perl #46947]
435
436 =back
437
438 =head1 Known Problems
439
440 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
441 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
442 platform specific bugs also go here.
443
444 [ List each fix as a =item entry ]
445
446 =over 4
447
448 =item *
449
450 XXX
451
452 =back
453
454 =head1 Errata From Previous Releases
455
456 =over 4
457
458 =item *
459
460 XXX Add anything here that we forgot to add, or were mistaken about, in
461 the perldelta of a previous release.
462
463 =back
464
465 =head1 Obituary
466
467 XXX If any significant core contributor has died, we've added a short obituary
468 here.
469
470 =head1 Acknowledgements
471
472 XXX Generate this with:
473
474   perl Porting/acknowledgements.pl v5.21.2..HEAD
475
476 =head1 Reporting Bugs
477
478 If you find what you think is a bug, you might check the articles recently
479 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
480 https://rt.perl.org/ .  There may also be information at
481 http://www.perl.org/ , the Perl Home Page.
482
483 If you believe you have an unreported bug, please run the L<perlbug> program
484 included with your release.  Be sure to trim your bug down to a tiny but
485 sufficient test case.  Your bug report, along with the output of C<perl -V>,
486 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
487
488 If the bug you are reporting has security implications, which make it
489 inappropriate to send to a publicly archived mailing list, then please send it
490 to perl5-security-report@perl.org.  This points to a closed subscription
491 unarchived mailing list, which includes all the core committers, who will be
492 able to help assess the impact of issues, figure out a resolution, and help
493 co-ordinate the release of patches to mitigate or fix the problem across all
494 platforms on which Perl is supported.  Please only use this address for
495 security issues in the Perl core, not for modules independently distributed on
496 CPAN.
497
498 =head1 SEE ALSO
499
500 The F<Changes> file for an explanation of how to view exhaustive details on
501 what changed.
502
503 The F<INSTALL> file for how to build Perl.
504
505 The F<README> file for general stuff.
506
507 The F<Artistic> and F<Copying> files for copyright information.
508
509 =cut