This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta entry for v5.31.1-101-g5c696bd319
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
dad02c36
KE
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.2
d407e309 9
862f380b 10=head1 DESCRIPTION
261e14b0 11
dad02c36 12This document describes differences between the 5.31.1 release and the 5.31.2
862f380b 13release.
261e14b0 14
dad02c36
KE
15If you are upgrading from an earlier release such as 5.31.0, first read
16L<perl5311delta>, which describes differences between 5.31.0 and 5.31.1.
8424e368 17
dad02c36 18=head1 Notice
8424e368 19
dad02c36 20XXX Any important notices here
8424e368 21
dad02c36 22=head1 Core Enhancements
8424e368 23
dad02c36
KE
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.
0240db1e 27
dad02c36 28[ List each enhancement as a =head2 entry ]
0240db1e 29
dad02c36 30=head1 Security
53f11efa 31
dad02c36
KE
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.
53f11efa 35
dad02c36 36[ List each security issue as a =head2 entry ]
d407e309 37
dad02c36 38=head1 Incompatible Changes
8424e368 39
dad02c36 40XXX For a release on a stable branch, this section aspires to be:
8424e368 41
dad02c36
KE
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.
8424e368 45
dad02c36 46[ List each incompatible change as a =head2 entry ]
8424e368 47
dad02c36 48=head1 Deprecations
a0348300 49
dad02c36 50XXX Any deprecated features, syntax, modules etc. should be listed here.
8424e368 51
dad02c36 52=head2 Module removals
8424e368 53
dad02c36 54XXX Remove this section if not applicable.
8424e368 55
dad02c36
KE
56The following modules will be removed from the core distribution in a
57future release, and will at that time need to be installed from CPAN.
58Distributions on CPAN which require these modules will need to list them as
59prerequisites.
8424e368 60
dad02c36
KE
61The core versions of these modules will now issue C<"deprecated">-category
62warnings to alert you to this fact. To silence these deprecation warnings,
63install the modules in question from CPAN.
7b97bf55 64
dad02c36
KE
65Note that these are (with rare exceptions) fine modules that you are encouraged
66to continue to use. Their disinclusion from core primarily hinges on their
67necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68not usually on concerns over their design.
a0348300 69
dad02c36 70=over
a0348300 71
dad02c36 72=item XXX
a0348300 73
dad02c36
KE
74XXX Note that deprecated modules should be listed here even if they are listed
75as an updated module in the L</Modules and Pragmata> section.
a0348300 76
dad02c36 77=back
a0348300 78
dad02c36 79[ List each other deprecation as a =head2 entry ]
a0348300 80
dad02c36 81=head1 Performance Enhancements
a0348300 82
dad02c36
KE
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
a0348300 85
dad02c36 86[ List each enhancement as an =item entry ]
a0348300 87
dad02c36 88=over 4
7b97bf55 89
9409f532 90=item *
7b97bf55 91
dad02c36 92XXX
cc1cbb06 93
dad02c36 94=back
a0348300 95
dad02c36 96=head1 Modules and Pragmata
a0348300 97
dad02c36
KE
98XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
99go here. If Module::CoreList is updated, generate an initial draft of the
100following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
101for important changes should then be added by hand. In an ideal world,
102dual-life modules would have a F<Changes> file that could be cribbed.
a0348300 103
dad02c36
KE
104The list of new and updated modules is modified automatically as part of
105preparing a Perl release, so the only reason to manually add entries here is if
106you're summarising the important changes in the module update. (Also, if the
107manually-added details don't match the automatically-generated ones, the
108release manager will have to investigate the situation carefully.)
a0348300 109
dad02c36 110[ Within each section, list entries as an =item entry ]
a0348300 111
dad02c36 112=head2 New Modules and Pragmata
a0348300 113
dad02c36 114=over 4
a0348300
KE
115
116=item *
117
dad02c36 118XXX Remove this section if not applicable.
a0348300 119
dad02c36 120=back
a0348300 121
dad02c36
KE
122=head2 Updated Modules and Pragmata
123
124=over 4
a0348300
KE
125
126=item *
127
dad02c36 128L<XXX> has been upgraded from version A.xx to B.yy.
a0348300 129
dad02c36 130If there was something important to note about this change, include that here.
a0348300 131
dad02c36
KE
132=back
133
134=head2 Removed Modules and Pragmata
135
136=over 4
cc1cbb06
TC
137
138=item *
139
dad02c36 140XXX
8424e368 141
dad02c36 142=back
a0348300 143
dad02c36 144=head1 Documentation
a0348300 145
dad02c36
KE
146XXX Changes to files in F<pod/> go here. Consider grouping entries by
147file and be sure to link to the appropriate page, e.g. L<perlfunc>.
a0348300 148
dad02c36 149=head2 New Documentation
a0348300 150
dad02c36 151XXX Changes which create B<new> files in F<pod/> go here.
a0348300 152
dad02c36 153=head3 L<XXX>
a0348300 154
dad02c36 155XXX Description of the purpose of the new file here
a0348300 156
dad02c36 157=head2 Changes to Existing Documentation
a0348300 158
dad02c36
KE
159We have attempted to update the documentation to reflect the changes
160listed in this document. If you find any we have missed, send email
161to L<perlbug@perl.org|mailto:perlbug@perl.org>.
a0348300 162
dad02c36
KE
163XXX Changes which significantly change existing files in F<pod/> go here.
164However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
165section.
a0348300 166
dad02c36 167Additionally, the following selected changes have been made:
a0348300 168
dad02c36 169=head3 L<XXX>
a0348300 170
dad02c36 171=over 4
a0348300
KE
172
173=item *
174
dad02c36 175XXX Description of the change here
a0348300 176
dad02c36 177=back
a0348300 178
dad02c36 179=head1 Diagnostics
a0348300 180
dad02c36
KE
181The following additions or changes have been made to diagnostic output,
182including warnings and fatal error messages. For the complete list of
183diagnostic messages, see L<perldiag>.
a0348300 184
dad02c36
KE
185XXX New or changed warnings emitted by the core's C<C> code go here. Also
186include any changes in L<perldiag> that reconcile it to the C<C> code.
8424e368 187
dad02c36 188=head2 New Diagnostics
8424e368 189
dad02c36
KE
190XXX Newly added diagnostic messages go under here, separated into New Errors
191and New Warnings
192
193=head3 New Errors
8424e368
S
194
195=over 4
196
197=item *
198
dad02c36 199XXX L<message|perldiag/"message">
8424e368
S
200
201=back
202
dad02c36 203=head3 New Warnings
8424e368 204
dad02c36 205=over 4
8424e368 206
dad02c36 207=item *
8424e368 208
dad02c36 209XXX L<message|perldiag/"message">
8424e368 210
dad02c36
KE
211=back
212
213=head2 Changes to Existing Diagnostics
214
215XXX Changes (i.e. rewording) of diagnostic messages go here
860a458f
KE
216
217=over 4
218
219=item *
220
1a7108fe
KW
221C<\N{} here is restricted to one character> is now emitted in the same
222circumstances where previously C<\N{} in inverted character class or as
223a range end-point is restricted to one character> was.
224
225This is due to new circumstances having been added in perl v5.30 that
226weren't covered by the earlier wording.
860a458f
KE
227
228=back
229
dad02c36
KE
230=head1 Utility Changes
231
232XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
233Most of these are built within the directory F<utils>.
234
235[ List utility changes as a =head2 entry for each utility and =item
236entries for each change
237Use L<XXX> with program names to get proper documentation linking. ]
238
239=head2 L<XXX>
8424e368
S
240
241=over 4
d407e309 242
d407e309
S
243=item *
244
dad02c36 245XXX
8424e368
S
246
247=back
248
8424e368
S
249=head1 Configuration and Compilation
250
dad02c36
KE
251XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
252go here. Any other changes to the Perl build process should be listed here.
253However, any platform-specific changes should be listed in the
254L</Platform Support> section, instead.
255
256[ List changes as an =item entry ].
257
8424e368
S
258=over 4
259
260=item *
261
48988e37
TC
262The C<ECHO> macro is now defined. This is used in a C<dtrace> rule
263that was originally changed for FreeBSD, and the FreeBSD make
264apparently predefines it. The Solaris make does not predefine C<ECHO>
265which broke this rule on Solaris. [perl #134218]
8424e368
S
266
267=back
268
dad02c36 269=head1 Testing
8424e368 270
dad02c36
KE
271XXX Any significant changes to the testing of a freshly built perl should be
272listed here. Changes which create B<new> files in F<t/> go here as do any
273large changes to the testing harness (e.g. when parallel testing was added).
274Changes to existing files in F<t/> aren't worth summarizing, although the bugs
275that they represent may be covered elsewhere.
8424e368 276
dad02c36 277XXX If there were no significant test changes, say this:
8424e368 278
dad02c36
KE
279Tests were added and changed to reflect the other additions and changes
280in this release.
8424e368 281
dad02c36 282XXX If instead there were significant changes, say this:
8424e368 283
dad02c36
KE
284Tests were added and changed to reflect the other additions and
285changes in this release. Furthermore, these significant changes were
286made:
8424e368 287
dad02c36 288[ List each test improvement as an =item entry ]
8424e368 289
8424e368
S
290=over 4
291
292=item *
293
dad02c36 294XXX
8424e368
S
295
296=back
297
dad02c36 298=head1 Platform Support
8424e368 299
dad02c36 300XXX Any changes to platform support should be listed in the sections below.
8424e368 301
dad02c36
KE
302[ Within the sections, list each platform as an =item entry with specific
303changes as paragraphs below it. ]
8424e368 304
dad02c36 305=head2 New Platforms
b9d9f9ab 306
dad02c36
KE
307XXX List any platforms that this version of perl compiles on, that previous
308versions did not. These will either be enabled by new files in the F<hints/>
309directories, or new subdirectories and F<README> files at the top level of the
310source tree.
b9d9f9ab 311
dad02c36 312=over 4
8424e368 313
dad02c36 314=item XXX-some-platform
ddf10889 315
dad02c36 316XXX
ddf10889 317
dad02c36 318=back
755e4cab 319
dad02c36 320=head2 Discontinued Platforms
755e4cab 321
dad02c36 322XXX List any platforms that this version of perl no longer compiles on.
fef47ada 323
dad02c36 324=over 4
09b83c41 325
dad02c36 326=item XXX-some-platform
09b83c41 327
dad02c36 328XXX
09b83c41 329
dad02c36 330=back
09b83c41 331
dad02c36 332=head2 Platform-Specific Notes
fef47ada 333
dad02c36
KE
334XXX List any changes for specific platforms. This could include configuration
335and compilation changes or changes in portability/compatibility. However,
336changes within modules for platforms should generally be listed in the
337L</Modules and Pragmata> section.
4ec3954c 338
dad02c36 339=over 4
4ec3954c 340
ec121dac
TC
341=item Linux
342
343C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>. [perl
344#134189]
345
c6981b9a 346=item VMS
4ec3954c 347
c6981b9a 348C<-Duse64bitint> is now the default on VMS.
4ec3954c 349
dad02c36 350=back
4ec3954c 351
dad02c36 352=head1 Internal Changes
4ec3954c 353
dad02c36
KE
354XXX Changes which affect the interface available to C<XS> code go here. Other
355significant internal changes for future core maintainers should be noted as
356well.
4ec3954c 357
dad02c36 358[ List each change as an =item entry ]
4ec3954c 359
dad02c36 360=over 4
4ec3954c
TC
361
362=item *
363
26552905
DM
364The PERL_DESTRUCT_LEVEL environment variable was formerly only honored on
365perl binaries built with DEBUGGING support. It it now checked on all perl
366builds. It's normal use is to force perl to individually free every block
367of memory which it has allocated before exiting, which is useful when
368using automated leak detection tools such as valgrind.
4ec3954c
TC
369
370=back
371
dad02c36 372=head1 Selected Bug Fixes
4ec3954c 373
dad02c36
KE
374XXX Important bug fixes in the core language are summarized here. Bug fixes in
375files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
2dd5ef16 376
dad02c36
KE
377[ List each fix as an =item entry ]
378
379=over 4
2dd5ef16 380
5b2f1ba6
TC
381=item *
382
1bed9104
TC
383Parsing incomplete hex or binary literals was changed in 5.31.1 to
384treat such a literal as just the 0, leaving the following C<x> or C<b>
385to be parsed as part of the next token. This could lead to some
386silent changes in behaviour, so now incomplete hex or binary literals
387produce a fatal error. [perl #134125]
5b2f1ba6 388
dad02c36 389=back
5b2f1ba6 390
dad02c36 391=head1 Known Problems
5b2f1ba6 392
dad02c36
KE
393XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
394tests that had to be C<TODO>ed for the release would be noted here. Unfixed
395platform specific bugs also go here.
0367cc1a 396
dad02c36 397[ List each fix as an =item entry ]
0367cc1a 398
dad02c36 399=over 4
84ab3b69 400
fa068f6d
TC
401=item *
402
dad02c36 403XXX
fa068f6d 404
8424e368
S
405=back
406
dad02c36 407=head1 Errata From Previous Releases
8424e368 408
dad02c36 409=over 4
a0348300 410
dad02c36 411=item *
a0348300 412
dad02c36
KE
413XXX Add anything here that we forgot to add, or were mistaken about, in
414the perldelta of a previous release.
a0348300 415
dad02c36 416=back
a0348300 417
dad02c36
KE
418=head1 Obituary
419
420XXX If any significant core contributor or member of the CPAN community has
421died, add a short obituary here.
422
423=head1 Acknowledgements
a0348300 424
dad02c36 425XXX Generate this with:
8424e368 426
dad02c36 427 perl Porting/acknowledgements.pl v5.31.1..HEAD
8424e368 428
44691e6f
AB
429=head1 Reporting Bugs
430
373fec1e 431If you find what you think is a bug, you might check the perl bug database
15f62f05
KE
432at L<https://rt.perl.org/>. There may also be information at
433L<http://www.perl.org/>, the Perl Home Page.
44691e6f 434
e08634c5
SH
435If you believe you have an unreported bug, please run the L<perlbug> program
436included with your release. Be sure to trim your bug down to a tiny but
437sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 438will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 439
87c118b9
DM
440If the bug you are reporting has security implications which make it
441inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
442L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
443for details of how to report the issue.
44691e6f 444
390ae6f9
S
445=head1 Give Thanks
446
373fec1e
SH
447If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
448you can do so by running the C<perlthanks> program:
390ae6f9
S
449
450 perlthanks
451
452This will send an email to the Perl 5 Porters list with your show of thanks.
453
44691e6f
AB
454=head1 SEE ALSO
455
e08634c5
SH
456The F<Changes> file for an explanation of how to view exhaustive details on
457what changed.
44691e6f
AB
458
459The F<INSTALL> file for how to build Perl.
460
461The F<README> file for general stuff.
462
463The F<Artistic> and F<Copying> files for copyright information.
464
465=cut