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