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