This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix upgrade notes in INSTALL
[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 266
86b50d93
DIM
267=item *
268
269Bison versions 3.1 through 3.4 are now supported.
270
8424e368
S
271=back
272
dad02c36 273=head1 Testing
8424e368 274
dad02c36
KE
275XXX Any significant changes to the testing of a freshly built perl should be
276listed here. Changes which create B<new> files in F<t/> go here as do any
277large changes to the testing harness (e.g. when parallel testing was added).
278Changes to existing files in F<t/> aren't worth summarizing, although the bugs
279that they represent may be covered elsewhere.
8424e368 280
dad02c36 281XXX If there were no significant test changes, say this:
8424e368 282
dad02c36
KE
283Tests were added and changed to reflect the other additions and changes
284in this release.
8424e368 285
dad02c36 286XXX If instead there were significant changes, say this:
8424e368 287
dad02c36
KE
288Tests were added and changed to reflect the other additions and
289changes in this release. Furthermore, these significant changes were
290made:
8424e368 291
dad02c36 292[ List each test improvement as an =item entry ]
8424e368 293
8424e368
S
294=over 4
295
296=item *
297
dad02c36 298XXX
8424e368
S
299
300=back
301
dad02c36 302=head1 Platform Support
8424e368 303
dad02c36 304XXX Any changes to platform support should be listed in the sections below.
8424e368 305
dad02c36
KE
306[ Within the sections, list each platform as an =item entry with specific
307changes as paragraphs below it. ]
8424e368 308
dad02c36 309=head2 New Platforms
b9d9f9ab 310
dad02c36
KE
311XXX List any platforms that this version of perl compiles on, that previous
312versions did not. These will either be enabled by new files in the F<hints/>
313directories, or new subdirectories and F<README> files at the top level of the
314source tree.
b9d9f9ab 315
dad02c36 316=over 4
8424e368 317
dad02c36 318=item XXX-some-platform
ddf10889 319
dad02c36 320XXX
ddf10889 321
dad02c36 322=back
755e4cab 323
dad02c36 324=head2 Discontinued Platforms
755e4cab 325
dad02c36 326XXX List any platforms that this version of perl no longer compiles on.
fef47ada 327
dad02c36 328=over 4
09b83c41 329
dad02c36 330=item XXX-some-platform
09b83c41 331
dad02c36 332XXX
09b83c41 333
dad02c36 334=back
09b83c41 335
dad02c36 336=head2 Platform-Specific Notes
fef47ada 337
dad02c36
KE
338XXX List any changes for specific platforms. This could include configuration
339and compilation changes or changes in portability/compatibility. However,
340changes within modules for platforms should generally be listed in the
341L</Modules and Pragmata> section.
4ec3954c 342
dad02c36 343=over 4
4ec3954c 344
ec121dac
TC
345=item Linux
346
347C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>. [perl
348#134189]
349
c6981b9a 350=item VMS
4ec3954c 351
c6981b9a 352C<-Duse64bitint> is now the default on VMS.
4ec3954c 353
dad02c36 354=back
4ec3954c 355
dad02c36 356=head1 Internal Changes
4ec3954c 357
dad02c36
KE
358XXX Changes which affect the interface available to C<XS> code go here. Other
359significant internal changes for future core maintainers should be noted as
360well.
4ec3954c 361
dad02c36 362[ List each change as an =item entry ]
4ec3954c 363
dad02c36 364=over 4
4ec3954c
TC
365
366=item *
367
26552905 368The PERL_DESTRUCT_LEVEL environment variable was formerly only honored on
06cc5386 369perl binaries built with DEBUGGING support. It is now checked on all perl
c22107ad 370builds. Its normal use is to force perl to individually free every block
26552905
DM
371of memory which it has allocated before exiting, which is useful when
372using automated leak detection tools such as valgrind.
4ec3954c 373
b870557c
TC
374=item *
375
376The API eval_sv() now accepts a C<G_RETHROW> flag. If this flag is
377set and an exception is thrown while compiling or executing the
378supplied code, it will be rethrown, and eval_sv() will not return.
379[perl #134177]
380
ed0cf058
TC
381=item *
382
383As part of the fix for [perl #2754] perl_parse() now returns non-zero
384if exit(0) is called in a C<BEGIN>, C<UNITCHECK> or C<CHECK> block.
385
4ec3954c
TC
386=back
387
dad02c36 388=head1 Selected Bug Fixes
4ec3954c 389
dad02c36
KE
390XXX Important bug fixes in the core language are summarized here. Bug fixes in
391files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
2dd5ef16 392
dad02c36
KE
393[ List each fix as an =item entry ]
394
395=over 4
2dd5ef16 396
5b2f1ba6
TC
397=item *
398
1bed9104
TC
399Parsing incomplete hex or binary literals was changed in 5.31.1 to
400treat such a literal as just the 0, leaving the following C<x> or C<b>
401to be parsed as part of the next token. This could lead to some
402silent changes in behaviour, so now incomplete hex or binary literals
403produce a fatal error. [perl #134125]
5b2f1ba6 404
b870557c
TC
405=item *
406
407eval_pv()'s I<croak_on_error> flag will now throw even if the
408exception is a false overloaded value. [perl #134177]
409
ed0cf058
TC
410=item *
411
412C<INIT> blocks and the program itself are no longer run if exit(0) is
413called within a C<BEGIN>, C<UNITCHECK> or C<CHECK> block. [perl
414#2754]
415
973ae088
TC
416=item *
417
418C<<< open my $fh, ">>+", undef >>> now opens the temporary file in
419append mode - writes will seek to the end of file before writing.
420[perl #134221]
421
dad02c36 422=back
5b2f1ba6 423
dad02c36 424=head1 Known Problems
5b2f1ba6 425
dad02c36
KE
426XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
427tests that had to be C<TODO>ed for the release would be noted here. Unfixed
428platform specific bugs also go here.
0367cc1a 429
dad02c36 430[ List each fix as an =item entry ]
0367cc1a 431
dad02c36 432=over 4
84ab3b69 433
fa068f6d
TC
434=item *
435
dad02c36 436XXX
fa068f6d 437
8424e368
S
438=back
439
dad02c36 440=head1 Errata From Previous Releases
8424e368 441
dad02c36 442=over 4
a0348300 443
dad02c36 444=item *
a0348300 445
dad02c36
KE
446XXX Add anything here that we forgot to add, or were mistaken about, in
447the perldelta of a previous release.
a0348300 448
dad02c36 449=back
a0348300 450
dad02c36
KE
451=head1 Obituary
452
453XXX If any significant core contributor or member of the CPAN community has
454died, add a short obituary here.
455
456=head1 Acknowledgements
a0348300 457
dad02c36 458XXX Generate this with:
8424e368 459
dad02c36 460 perl Porting/acknowledgements.pl v5.31.1..HEAD
8424e368 461
44691e6f
AB
462=head1 Reporting Bugs
463
373fec1e 464If you find what you think is a bug, you might check the perl bug database
15f62f05
KE
465at L<https://rt.perl.org/>. There may also be information at
466L<http://www.perl.org/>, the Perl Home Page.
44691e6f 467
e08634c5
SH
468If you believe you have an unreported bug, please run the L<perlbug> program
469included with your release. Be sure to trim your bug down to a tiny but
470sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 471will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 472
87c118b9
DM
473If the bug you are reporting has security implications which make it
474inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
475L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
476for details of how to report the issue.
44691e6f 477
390ae6f9
S
478=head1 Give Thanks
479
373fec1e
SH
480If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
481you can do so by running the C<perlthanks> program:
390ae6f9
S
482
483 perlthanks
484
485This will send an email to the Perl 5 Porters list with your show of thanks.
486
44691e6f
AB
487=head1 SEE ALSO
488
e08634c5
SH
489The F<Changes> file for an explanation of how to view exhaustive details on
490what changed.
44691e6f
AB
491
492The F<INSTALL> file for how to build Perl.
493
494The F<README> file for general stuff.
495
496The F<Artistic> and F<Copying> files for copyright information.
497
498=cut