This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
23a1b58b290b14ac5818bc89389bec832f148bb1
[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.31.1
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.31.0 release and the 5.31.1
13 release.
14
15 If you are upgrading from an earlier release such as 5.30.0, first read
16 L<perl5310delta>, which describes differences between 5.30.0 and 5.31.0.
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 =head1 Deprecations
49
50 XXX Any deprecated features, syntax, modules etc. should be listed here.
51
52 =head2 Module removals
53
54 XXX Remove this section if not applicable.
55
56 The following modules will be removed from the core distribution in a
57 future release, and will at that time need to be installed from CPAN.
58 Distributions on CPAN which require these modules will need to list them as
59 prerequisites.
60
61 The core versions of these modules will now issue C<"deprecated">-category
62 warnings to alert you to this fact.  To silence these deprecation warnings,
63 install the modules in question from CPAN.
64
65 Note that these are (with rare exceptions) fine modules that you are encouraged
66 to continue to use.  Their disinclusion from core primarily hinges on their
67 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68 not usually on concerns over their design.
69
70 =over
71
72 =item XXX
73
74 XXX Note that deprecated modules should be listed here even if they are listed
75 as an updated module in the L</Modules and Pragmata> section.
76
77 =back
78
79 [ List each other deprecation as a =head2 entry ]
80
81 =head1 Performance Enhancements
82
83 XXX Changes which enhance performance without changing behaviour go here.
84 There may well be none in a stable release.
85
86 [ List each enhancement as an =item entry ]
87
88 =over 4
89
90 =item *
91
92 XXX
93
94 =back
95
96 =head1 Modules and Pragmata
97
98 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
99 go here.  If Module::CoreList is updated, generate an initial draft of the
100 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
101 for important changes should then be added by hand.  In an ideal world,
102 dual-life modules would have a F<Changes> file that could be cribbed.
103
104 The list of new and updated modules is modified automatically as part of
105 preparing a Perl release, so the only reason to manually add entries here is if
106 you're summarising the important changes in the module update. (Also, if the
107 manually-added details don't match the automatically-generated ones, the
108 release manager will have to investigate the situation carefully.)
109
110 [ Within each section, list entries as an =item entry ]
111
112 =head2 New Modules and Pragmata
113
114 =over 4
115
116 =item *
117
118 XXX Remove this section if not applicable.
119
120 =back
121
122 =head2 Updated Modules and Pragmata
123
124 =over 4
125
126 =item *
127
128 L<IO> has been upgraded from version 1.40 to 1.41.
129
130 The supplied I<TO> is now always honoured on calls to the send()
131 method.  [perl #133936]
132
133 =item *
134
135 L<Storable> has been upgraded from version 3.15 to 3.16.
136
137 Regular expressions objects weren't properly counted for object id
138 purposes on retrieve.  This would corrupt the resulting structure, or
139 cause a runtime error in some cases.  [perl #134179]
140
141 =back
142
143 =head2 Removed Modules and Pragmata
144
145 =over 4
146
147 =item *
148
149 Pod::Parser has been removed from the core distribution.
150 It still is available for download from CPAN.  This resolves [perl
151 #119439].
152
153 =back
154
155 =head1 Documentation
156
157 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
158 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
159
160 =head2 New Documentation
161
162 XXX Changes which create B<new> files in F<pod/> go here.
163
164 =head3 L<XXX>
165
166 XXX Description of the purpose of the new file here
167
168 =head2 Changes to Existing Documentation
169
170 We have attempted to update the documentation to reflect the changes
171 listed in this document.  If you find any we have missed, send email
172 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
173
174 XXX Changes which significantly change existing files in F<pod/> go here.
175 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
176 section.
177
178 Additionally, the following selected changes have been made:
179
180 =head3 L<XXX>
181
182 =over 4
183
184 =item *
185
186 XXX Description of the change here
187
188 =back
189
190 =head1 Diagnostics
191
192 The following additions or changes have been made to diagnostic output,
193 including warnings and fatal error messages.  For the complete list of
194 diagnostic messages, see L<perldiag>.
195
196 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
197 include any changes in L<perldiag> that reconcile it to the C<C> code.
198
199 =head2 New Diagnostics
200
201 XXX Newly added diagnostic messages go under here, separated into New Errors
202 and New Warnings
203
204 =head3 New Errors
205
206 =over 4
207
208 =item *
209
210 XXX L<message|perldiag/"message">
211
212 =back
213
214 =head3 New Warnings
215
216 =over 4
217
218 =item *
219
220 XXX L<message|perldiag/"message">
221
222 =back
223
224 =head2 Changes to Existing Diagnostics
225
226 XXX Changes (i.e. rewording) of diagnostic messages go here
227
228 =over 4
229
230 =item *
231
232 XXX Describe change here
233
234 =back
235
236 =head1 Utility Changes
237
238 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
239 Most of these are built within the directory F<utils>.
240
241 [ List utility changes as a =head2 entry for each utility and =item
242 entries for each change
243 Use L<XXX> with program names to get proper documentation linking. ]
244
245 =head2 L<XXX>
246
247 =over 4
248
249 =item *
250
251 XXX
252
253 =back
254
255 =head1 Configuration and Compilation
256
257 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
258 go here.  Any other changes to the Perl build process should be listed here.
259 However, any platform-specific changes should be listed in the
260 L</Platform Support> section, instead.
261
262 [ List changes as an =item entry ].
263
264 =over 4
265
266 =item *
267
268 XXX
269
270 =back
271
272 =head1 Testing
273
274 XXX Any significant changes to the testing of a freshly built perl should be
275 listed here.  Changes which create B<new> files in F<t/> go here as do any
276 large changes to the testing harness (e.g. when parallel testing was added).
277 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
278 that they represent may be covered elsewhere.
279
280 XXX If there were no significant test changes, say this:
281
282 Tests were added and changed to reflect the other additions and changes
283 in this release.
284
285 XXX If instead there were significant changes, say this:
286
287 Tests were added and changed to reflect the other additions and
288 changes in this release.  Furthermore, these significant changes were
289 made:
290
291 [ List each test improvement as an =item entry ]
292
293 =over 4
294
295 =item *
296
297 XXX
298
299 =back
300
301 =head1 Platform Support
302
303 XXX Any changes to platform support should be listed in the sections below.
304
305 [ Within the sections, list each platform as an =item entry with specific
306 changes as paragraphs below it. ]
307
308 =head2 New Platforms
309
310 XXX List any platforms that this version of perl compiles on, that previous
311 versions did not.  These will either be enabled by new files in the F<hints/>
312 directories, or new subdirectories and F<README> files at the top level of the
313 source tree.
314
315 =over 4
316
317 =item XXX-some-platform
318
319 XXX
320
321 =back
322
323 =head2 Discontinued Platforms
324
325 XXX List any platforms that this version of perl no longer compiles on.
326
327 =over 4
328
329 =item XXX-some-platform
330
331 XXX
332
333 =back
334
335 =head2 Platform-Specific Notes
336
337 XXX List any changes for specific platforms.  This could include configuration
338 and compilation changes or changes in portability/compatibility.  However,
339 changes within modules for platforms should generally be listed in the
340 L</Modules and Pragmata> section.
341
342 =over 4
343
344 =item XXX-some-platform
345
346 XXX
347
348 =back
349
350 =head1 Internal Changes
351
352 XXX Changes which affect the interface available to C<XS> code go here.  Other
353 significant internal changes for future core maintainers should be noted as
354 well.
355
356 [ List each change as an =item entry ]
357
358 =over 4
359
360 =item *
361
362 L<eval_pv()|perlapi/eval_pv> no longer stringifies the exception when
363 C<croak_on_error> is true.  [perl #134175]
364
365 =back
366
367 =head1 Selected Bug Fixes
368
369 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
370 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
371
372 [ List each fix as an =item entry ]
373
374 =over 4
375
376 =item *
377
378 Setting C<$)> now properly sets supplementary group ids, if you have
379 the necessary privileges.  [perl #134169]
380
381 =item *
382
383 close() on a pipe now preemptively clears the PerlIO object from the
384 IO SV.  This prevents a second attempt to close the already closed
385 PerlIO object if a signal handler calls die() or exit() while close()
386 is waiting for the child process to complete.  [perl #122112]
387
388 =item *
389
390 C<< sprintf("%.*a", -10000, $x) >> would cause a buffer overflow due
391 to mishandling of the negative precision value.  [perl #134008]
392
393 =item *
394
395 scalar() on a reference could cause an erroneous assertion failure
396 during compilation.  [perl #134045]
397
398 =item *
399
400 Extraordinarily large (over 2GB) floating point format widths could
401 cause an integer overflow in the underlying call to snprintf(),
402 resulting in an assertion.  Formatted floating point widths are now
403 limited to the range of int, the return value of snprintf().  [perl
404 #133913]
405
406 =item *
407
408 Parsing the following constructs within a sub-parse (such as with
409 C<"${code here}"> or C<s/.../code here/e>) has changed to match how
410 they're parsed normally:
411
412 =over
413
414 =item *
415
416 C<print $fh ...> no longer produces a syntax error.
417
418 =item *
419
420 Code like C<s/.../ ${time} /e> now properly produces an "Ambiguous use
421 of ${time} resolved to $time at ..." warning when warnings are enabled.
422
423 =item *
424
425 C<@x {"a"}> (with the space) in a sub-parse now properly produces a
426 "better written as" warning when warnings are enabled.
427
428 =item *
429
430 attributes can now be used in a sub-parse.
431
432 =back
433
434 [perl #133850]
435
436 =item *
437
438 Incomplete hex and binary literals like C<0x> and C<0b> are now
439 treated as if the C<x> or C<b> is part of the next token.  [perl
440 #134125]
441
442 =item *
443
444 A spurious C<)> in a subparse, such as in C<s/.../code here/e> or
445 C<"...${code here}">, no longer confuses the parser.
446
447 Previously a subparse was bracketed with generated C<(> and C<)>
448 tokens, so a spurious C<)> would close the construct without doing the
449 normal subparse clean up, confusing the parser and possible causing an
450 assertion failure.
451
452 Such constructs are now surrounded by artificial tokens that can't be
453 included in the source.  [perl #130585]
454
455 =item *
456
457 Reference assignment of a sub, such as C<\&foo = \&bar;>, silently did
458 nothing in the C<main::> package.  [perl #134072]
459
460 =item *
461
462 sv_gets() now recovers better if the target SV is modified by a signal
463 handler.  [perl #134035]
464
465 =item *
466
467 C<readline @foo> now evaluates C<@foo> in scalar context.  Previously
468 it would be evalauted in list context, and since readline() pops only
469 one argument from the stack, the stack could underflow, or be left
470 with unexpected values on the stack.  [perl #133989]
471
472 =back
473
474 =head1 Known Problems
475
476 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
477 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
478 platform specific bugs also go here.
479
480 [ List each fix as an =item entry ]
481
482 =over 4
483
484 =item *
485
486 XXX
487
488 =back
489
490 =head1 Errata From Previous Releases
491
492 =over 4
493
494 =item *
495
496 XXX Add anything here that we forgot to add, or were mistaken about, in
497 the perldelta of a previous release.
498
499 =back
500
501 =head1 Obituary
502
503 XXX If any significant core contributor or member of the CPAN community has
504 died, add a short obituary here.
505
506 =head1 Acknowledgements
507
508 XXX Generate this with:
509
510   perl Porting/acknowledgements.pl v5.31.0..HEAD
511
512 =head1 Reporting Bugs
513
514 If you find what you think is a bug, you might check the perl bug database
515 at L<https://rt.perl.org/>.  There may also be information at
516 L<http://www.perl.org/>, the Perl Home Page.
517
518 If you believe you have an unreported bug, please run the L<perlbug> program
519 included with your release.  Be sure to trim your bug down to a tiny but
520 sufficient test case.  Your bug report, along with the output of C<perl -V>,
521 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
522
523 If the bug you are reporting has security implications which make it
524 inappropriate to send to a publicly archived mailing list, then see
525 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
526 for details of how to report the issue.
527
528 =head1 Give Thanks
529
530 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
531 you can do so by running the C<perlthanks> program:
532
533     perlthanks
534
535 This will send an email to the Perl 5 Porters list with your show of thanks.
536
537 =head1 SEE ALSO
538
539 The F<Changes> file for an explanation of how to view exhaustive details on
540 what changed.
541
542 The F<INSTALL> file for how to build Perl.
543
544 The F<README> file for general stuff.
545
546 The F<Artistic> and F<Copying> files for copyright information.
547
548 =cut