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