This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 933e3e630076
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
9064626f
SH
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.31.3
d407e309 9
862f380b 10=head1 DESCRIPTION
261e14b0 11
9064626f 12This document describes differences between the 5.31.2 release and the 5.31.3
862f380b 13release.
261e14b0 14
9064626f
SH
15If you are upgrading from an earlier release such as 5.31.1, first read
16L<perl5312delta>, which describes differences between 5.31.1 and 5.31.2.
8424e368 17
9064626f 18=head1 Notice
a0348300 19
9064626f
SH
20XXX Any important notices here
21
22=head1 Core Enhancements
23
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
27
28[ List each enhancement as a =head2 entry ]
29
30=head1 Security
31
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
35
36[ List each security issue as a =head2 entry ]
37
38=head1 Incompatible Changes
39
40XXX 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
e6132dc0
TC
48=head2 Plain "0" string now treated as a number for range operator
49
50Previously a range C< "0" .. "-1" > would produce a range of numeric
51strings from "0" through "99", this now produces an empty list, just
52as C< 0 .. -1 > does.
53
54This was due to a special case that treated strings starting with "0"
55as strings so ranges like C< "00" .. "03" > produced C< "00", "01",
56"02", "03" >, but didn't specially handle the string C<"0">.
57
58[perl #133695]
59
9064626f
SH
60=head1 Deprecations
61
62XXX Any deprecated features, syntax, modules etc. should be listed here.
63
64=head2 Module removals
65
66XXX Remove this section if not applicable.
67
68The following modules will be removed from the core distribution in a
69future release, and will at that time need to be installed from CPAN.
70Distributions on CPAN which require these modules will need to list them as
71prerequisites.
72
73The core versions of these modules will now issue C<"deprecated">-category
74warnings to alert you to this fact. To silence these deprecation warnings,
75install the modules in question from CPAN.
76
77Note that these are (with rare exceptions) fine modules that you are encouraged
78to continue to use. Their disinclusion from core primarily hinges on their
79necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
80not usually on concerns over their design.
81
82=over
83
84=item XXX
85
86XXX Note that deprecated modules should be listed here even if they are listed
87as an updated module in the L</Modules and Pragmata> section.
88
89=back
90
91[ List each other deprecation as a =head2 entry ]
92
93=head1 Performance Enhancements
94
95XXX Changes which enhance performance without changing behaviour go here.
96There may well be none in a stable release.
97
98[ List each enhancement as an =item entry ]
a0348300 99
9c600b76 100=over 4
a0348300 101
9c600b76 102=item *
a0348300 103
9064626f 104XXX
a0348300 105
9064626f 106=back
9c600b76 107
9064626f 108=head1 Modules and Pragmata
a0348300 109
9064626f
SH
110XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
111go here. If Module::CoreList is updated, generate an initial draft of the
112following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
113for important changes should then be added by hand. In an ideal world,
114dual-life modules would have a F<Changes> file that could be cribbed.
a0348300 115
9064626f
SH
116The list of new and updated modules is modified automatically as part of
117preparing a Perl release, so the only reason to manually add entries here is if
118you're summarising the important changes in the module update. (Also, if the
119manually-added details don't match the automatically-generated ones, the
120release manager will have to investigate the situation carefully.)
a0348300 121
9064626f
SH
122[ Within each section, list entries as an =item entry ]
123
124=head2 New Modules and Pragmata
a0348300 125
9064626f 126=over 4
dad02c36 127
9c600b76
SH
128=item *
129
9064626f 130XXX Remove this section if not applicable.
a0348300 131
9064626f 132=back
a0348300 133
9064626f
SH
134=head2 Updated Modules and Pragmata
135
136=over 4
a0348300 137
9c600b76 138=item *
a0348300 139
03b7d279
TC
140L<Devel::PPPort> has been upgraded from version 3.54 to 3.55.
141
142The test files generated on Win32 are now identical to when they are
143generated on POSIX-like systems.
144
145=item *
146
147L<File::Find> has been upgraded from version 1.36 to 1.37.
148
149On Win32, the tests no longer require either a file in the drive root
150directory, or a writable root directory.
151
152=item *
153
36bb8f68
JK
154L<Thread> has been upgraded from version 3.04 to 3.05.
155
156=item *
157
9064626f
SH
158L<XXX> has been upgraded from version A.xx to B.yy.
159
160If there was something important to note about this change, include that here.
161
162=back
163
164=head2 Removed Modules and Pragmata
165
166=over 4
dad02c36 167
9c600b76 168=item *
dad02c36 169
9064626f
SH
170XXX
171
172=back
173
174=head1 Documentation
175
176XXX Changes to files in F<pod/> go here. Consider grouping entries by
177file and be sure to link to the appropriate page, e.g. L<perlfunc>.
178
179=head2 New Documentation
180
181XXX Changes which create B<new> files in F<pod/> go here.
182
183=head3 L<XXX>
184
185XXX Description of the purpose of the new file here
186
187=head2 Changes to Existing Documentation
188
189We have attempted to update the documentation to reflect the changes
190listed in this document. If you find any we have missed, send email
191to L<perlbug@perl.org|mailto:perlbug@perl.org>.
192
193XXX Changes which significantly change existing files in F<pod/> go here.
194However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
195section.
196
197Additionally, the following selected changes have been made:
198
199=head3 L<XXX>
200
201=over 4
cc1cbb06
TC
202
203=item *
204
9064626f 205XXX Description of the change here
8424e368 206
dad02c36 207=back
a0348300 208
dad02c36 209=head1 Diagnostics
a0348300 210
9064626f
SH
211The following additions or changes have been made to diagnostic output,
212including warnings and fatal error messages. For the complete list of
213diagnostic messages, see L<perldiag>.
214
215XXX New or changed warnings emitted by the core's C<C> code go here. Also
216include any changes in L<perldiag> that reconcile it to the C<C> code.
217
dad02c36 218=head2 New Diagnostics
8424e368 219
9064626f
SH
220XXX Newly added diagnostic messages go under here, separated into New Errors
221and New Warnings
222
dad02c36 223=head3 New Errors
8424e368
S
224
225=over 4
226
227=item *
228
9064626f 229XXX L<message|perldiag/"message">
8424e368 230
9064626f
SH
231=back
232
233=head3 New Warnings
234
235=over 4
236
237=item *
238
239XXX L<message|perldiag/"message">
8424e368 240
dad02c36
KE
241=back
242
243=head2 Changes to Existing Diagnostics
244
9064626f
SH
245XXX Changes (i.e. rewording) of diagnostic messages go here
246
860a458f
KE
247=over 4
248
249=item *
250
9064626f
SH
251XXX Describe change here
252
253=back
254
255=head1 Utility Changes
256
257XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
258Most of these are built within the directory F<utils>.
259
260[ List utility changes as a =head2 entry for each utility and =item
261entries for each change
262Use L<XXX> with program names to get proper documentation linking. ]
263
264=head2 L<XXX>
265
266=over 4
267
268=item *
1a7108fe 269
9064626f 270XXX
860a458f
KE
271
272=back
273
8424e368
S
274=head1 Configuration and Compilation
275
9064626f
SH
276XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
277go here. Any other changes to the Perl build process should be listed here.
278However, any platform-specific changes should be listed in the
279L</Platform Support> section, instead.
280
281[ List changes as an =item entry ].
282
8424e368
S
283=over 4
284
285=item *
286
9064626f
SH
287XXX
288
289=back
290
291=head1 Testing
292
293XXX Any significant changes to the testing of a freshly built perl should be
294listed here. Changes which create B<new> files in F<t/> go here as do any
295large changes to the testing harness (e.g. when parallel testing was added).
296Changes to existing files in F<t/> aren't worth summarizing, although the bugs
297that they represent may be covered elsewhere.
298
299XXX If there were no significant test changes, say this:
300
301Tests were added and changed to reflect the other additions and changes
302in this release.
303
304XXX If instead there were significant changes, say this:
305
306Tests were added and changed to reflect the other additions and
307changes in this release. Furthermore, these significant changes were
308made:
309
310[ List each test improvement as an =item entry ]
311
312=over 4
8424e368 313
86b50d93
DIM
314=item *
315
9064626f 316XXX
86b50d93 317
8424e368
S
318=back
319
dad02c36 320=head1 Platform Support
8424e368 321
9064626f 322XXX Any changes to platform support should be listed in the sections below.
fef47ada 323
9064626f
SH
324[ Within the sections, list each platform as an =item entry with specific
325changes as paragraphs below it. ]
4ec3954c 326
9064626f 327=head2 New Platforms
ec121dac 328
9064626f
SH
329XXX List any platforms that this version of perl compiles on, that previous
330versions did not. These will either be enabled by new files in the F<hints/>
331directories, or new subdirectories and F<README> files at the top level of the
332source tree.
ec121dac 333
9064626f 334=over 4
4ec3954c 335
9064626f
SH
336=item XXX-some-platform
337
338XXX
4ec3954c 339
dad02c36 340=back
4ec3954c 341
9064626f 342=head2 Discontinued Platforms
4ec3954c 343
9064626f 344XXX List any platforms that this version of perl no longer compiles on.
4ec3954c 345
9064626f 346=over 4
4ec3954c 347
9064626f 348=item XXX-some-platform
4ec3954c 349
9064626f 350XXX
b870557c 351
9064626f 352=back
b870557c 353
9064626f 354=head2 Platform-Specific Notes
ed0cf058 355
9064626f
SH
356XXX List any changes for specific platforms. This could include configuration
357and compilation changes or changes in portability/compatibility. However,
358changes within modules for platforms should generally be listed in the
359L</Modules and Pragmata> section.
ed0cf058 360
9064626f 361=over 4
f7faf2ad 362
efb1f9ac 363=item Windows
f7faf2ad 364
efb1f9ac
TC
365F<t/op/magic.t> could fail if environment varables starting with
366C<FOO> already existed.
f7faf2ad 367
4ec3954c
TC
368=back
369
9064626f 370=head1 Internal Changes
4ec3954c 371
9064626f
SH
372XXX Changes which affect the interface available to C<XS> code go here. Other
373significant internal changes for future core maintainers should be noted as
374well.
2dd5ef16 375
9064626f 376[ List each change as an =item entry ]
5b2f1ba6 377
9064626f 378=over 4
5b2f1ba6 379
b870557c
TC
380=item *
381
996b0cb8
PLE
382A new parser function L<parse_subsignature()|perlapi/parse_subsignature>
383allows a keyword plugin to parse a subroutine signature while C<use feature
384'signatures'> is in effect. This allows custom keywords to implement
385semantics similar to regular C<sub> declarations that include signatures.
386[perl #132474]
b870557c 387
061637ca
HS
388=item *
389
390Since on some platforms we need to hold a mutex when temporarily
391switching locales, new macros (C<STORE_LC_NUMERIC_SET_TO_NEEDED_IN>,
392C<WITH_LC_NUMERIC_SET_TO_NEEDED> and C<WITH_LC_NUMERIC_SET_TO_NEEDED_IN>)
393have been added to make it easier to do this safely and efficiently
394as part of [perl #134172].
395
9064626f 396=back
ed0cf058 397
9064626f 398=head1 Selected Bug Fixes
ed0cf058 399
9064626f
SH
400XXX Important bug fixes in the core language are summarized here. Bug fixes in
401files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
973ae088 402
9064626f
SH
403[ List each fix as an =item entry ]
404
405=over 4
973ae088 406
f7faf2ad
SH
407=item *
408
052ce2b8
TC
409C<< $@ = 100; die; >> now correctly propagates the 100 as an exception
410instead of ignoring it. [perl #134291]
f7faf2ad 411
a3c77565
TC
412=item *
413
414C<< 0 0x@ >> no longer asserts in S_no_op(). [perl #134310]
415
6e23836a
TC
416=item *
417
418Exceptions thrown while C<$@> is read-only could result in infinite
419recursion as perl tried to update C<$@>, which throws another
420exception, resulting in a stack overflow. Perl now replaces C<$@>
421with a copy if it's not a simple writable SV. [perl #134266]
422
dad02c36 423=back
5b2f1ba6 424
dad02c36 425=head1 Known Problems
5b2f1ba6 426
9064626f
SH
427XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
428tests that had to be C<TODO>ed for the release would be noted here. Unfixed
429platform specific bugs also go here.
84ab3b69 430
9064626f 431[ List each fix as an =item entry ]
fa068f6d 432
9064626f 433=over 4
cb561db1
SH
434
435=item *
436
9064626f 437XXX
fa068f6d 438
8424e368
S
439=back
440
9064626f
SH
441=head1 Errata From Previous Releases
442
443=over 4
a0348300 444
9064626f
SH
445=item *
446
447XXX Add anything here that we forgot to add, or were mistaken about, in
448the perldelta of a previous release.
8424e368 449
9064626f 450=back
a01eaaa1 451
9064626f 452=head1 Obituary
a01eaaa1 453
9064626f
SH
454XXX If any significant core contributor or member of the CPAN community has
455died, add a short obituary here.
a01eaaa1 456
9064626f 457=head1 Acknowledgements
a01eaaa1 458
9064626f 459XXX Generate this with:
a01eaaa1 460
9064626f 461 perl Porting/acknowledgements.pl v5.31.2..HEAD
8424e368 462
44691e6f
AB
463=head1 Reporting Bugs
464
9064626f
SH
465If you find what you think is a bug, you might check the perl bug database
466at L<https://rt.perl.org/>. There may also be information at
15f62f05 467L<http://www.perl.org/>, the Perl Home Page.
44691e6f 468
e08634c5
SH
469If you believe you have an unreported bug, please run the L<perlbug> program
470included with your release. Be sure to trim your bug down to a tiny but
471sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 472will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 473
87c118b9
DM
474If the bug you are reporting has security implications which make it
475inappropriate to send to a publicly archived mailing list, then see
9064626f
SH
476L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
477for details of how to report the issue.
44691e6f 478
390ae6f9
S
479=head1 Give Thanks
480
9064626f
SH
481If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
482you can do so by running the C<perlthanks> program:
390ae6f9
S
483
484 perlthanks
485
486This will send an email to the Perl 5 Porters list with your show of thanks.
487
44691e6f
AB
488=head1 SEE ALSO
489
e08634c5
SH
490The F<Changes> file for an explanation of how to view exhaustive details on
491what changed.
44691e6f
AB
492
493The F<INSTALL> file for how to build Perl.
494
495The F<README> file for general stuff.
496
497The F<Artistic> and F<Copying> files for copyright information.
498
499=cut