This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 1ef28cc363ae
[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
dad02c36 221XXX Describe change here
860a458f
KE
222
223=back
224
dad02c36
KE
225=head1 Utility Changes
226
227XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
228Most of these are built within the directory F<utils>.
229
230[ List utility changes as a =head2 entry for each utility and =item
231entries for each change
232Use L<XXX> with program names to get proper documentation linking. ]
233
234=head2 L<XXX>
8424e368
S
235
236=over 4
d407e309 237
d407e309
S
238=item *
239
dad02c36 240XXX
8424e368
S
241
242=back
243
8424e368
S
244=head1 Configuration and Compilation
245
dad02c36
KE
246XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
247go here. Any other changes to the Perl build process should be listed here.
248However, any platform-specific changes should be listed in the
249L</Platform Support> section, instead.
250
251[ List changes as an =item entry ].
252
8424e368
S
253=over 4
254
255=item *
256
dad02c36 257XXX
8424e368
S
258
259=back
260
dad02c36 261=head1 Testing
8424e368 262
dad02c36
KE
263XXX Any significant changes to the testing of a freshly built perl should be
264listed here. Changes which create B<new> files in F<t/> go here as do any
265large changes to the testing harness (e.g. when parallel testing was added).
266Changes to existing files in F<t/> aren't worth summarizing, although the bugs
267that they represent may be covered elsewhere.
8424e368 268
dad02c36 269XXX If there were no significant test changes, say this:
8424e368 270
dad02c36
KE
271Tests were added and changed to reflect the other additions and changes
272in this release.
8424e368 273
dad02c36 274XXX If instead there were significant changes, say this:
8424e368 275
dad02c36
KE
276Tests were added and changed to reflect the other additions and
277changes in this release. Furthermore, these significant changes were
278made:
8424e368 279
dad02c36 280[ List each test improvement as an =item entry ]
8424e368 281
8424e368
S
282=over 4
283
284=item *
285
dad02c36 286XXX
8424e368
S
287
288=back
289
dad02c36 290=head1 Platform Support
8424e368 291
dad02c36 292XXX Any changes to platform support should be listed in the sections below.
8424e368 293
dad02c36
KE
294[ Within the sections, list each platform as an =item entry with specific
295changes as paragraphs below it. ]
8424e368 296
dad02c36 297=head2 New Platforms
b9d9f9ab 298
dad02c36
KE
299XXX List any platforms that this version of perl compiles on, that previous
300versions did not. These will either be enabled by new files in the F<hints/>
301directories, or new subdirectories and F<README> files at the top level of the
302source tree.
b9d9f9ab 303
dad02c36 304=over 4
8424e368 305
dad02c36 306=item XXX-some-platform
ddf10889 307
dad02c36 308XXX
ddf10889 309
dad02c36 310=back
755e4cab 311
dad02c36 312=head2 Discontinued Platforms
755e4cab 313
dad02c36 314XXX List any platforms that this version of perl no longer compiles on.
fef47ada 315
dad02c36 316=over 4
09b83c41 317
dad02c36 318=item XXX-some-platform
09b83c41 319
dad02c36 320XXX
09b83c41 321
dad02c36 322=back
09b83c41 323
dad02c36 324=head2 Platform-Specific Notes
fef47ada 325
dad02c36
KE
326XXX List any changes for specific platforms. This could include configuration
327and compilation changes or changes in portability/compatibility. However,
328changes within modules for platforms should generally be listed in the
329L</Modules and Pragmata> section.
4ec3954c 330
dad02c36 331=over 4
4ec3954c 332
ec121dac
TC
333=item Linux
334
335C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>. [perl
336#134189]
337
c6981b9a 338=item VMS
4ec3954c 339
c6981b9a 340C<-Duse64bitint> is now the default on VMS.
4ec3954c 341
dad02c36 342=back
4ec3954c 343
dad02c36 344=head1 Internal Changes
4ec3954c 345
dad02c36
KE
346XXX Changes which affect the interface available to C<XS> code go here. Other
347significant internal changes for future core maintainers should be noted as
348well.
4ec3954c 349
dad02c36 350[ List each change as an =item entry ]
4ec3954c 351
dad02c36 352=over 4
4ec3954c
TC
353
354=item *
355
dad02c36 356XXX
4ec3954c
TC
357
358=back
359
dad02c36 360=head1 Selected Bug Fixes
4ec3954c 361
dad02c36
KE
362XXX Important bug fixes in the core language are summarized here. Bug fixes in
363files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
2dd5ef16 364
dad02c36
KE
365[ List each fix as an =item entry ]
366
367=over 4
2dd5ef16 368
5b2f1ba6
TC
369=item *
370
1bed9104
TC
371Parsing incomplete hex or binary literals was changed in 5.31.1 to
372treat such a literal as just the 0, leaving the following C<x> or C<b>
373to be parsed as part of the next token. This could lead to some
374silent changes in behaviour, so now incomplete hex or binary literals
375produce a fatal error. [perl #134125]
5b2f1ba6 376
dad02c36 377=back
5b2f1ba6 378
dad02c36 379=head1 Known Problems
5b2f1ba6 380
dad02c36
KE
381XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
382tests that had to be C<TODO>ed for the release would be noted here. Unfixed
383platform specific bugs also go here.
0367cc1a 384
dad02c36 385[ List each fix as an =item entry ]
0367cc1a 386
dad02c36 387=over 4
84ab3b69 388
fa068f6d
TC
389=item *
390
dad02c36 391XXX
fa068f6d 392
8424e368
S
393=back
394
dad02c36 395=head1 Errata From Previous Releases
8424e368 396
dad02c36 397=over 4
a0348300 398
dad02c36 399=item *
a0348300 400
dad02c36
KE
401XXX Add anything here that we forgot to add, or were mistaken about, in
402the perldelta of a previous release.
a0348300 403
dad02c36 404=back
a0348300 405
dad02c36
KE
406=head1 Obituary
407
408XXX If any significant core contributor or member of the CPAN community has
409died, add a short obituary here.
410
411=head1 Acknowledgements
a0348300 412
dad02c36 413XXX Generate this with:
8424e368 414
dad02c36 415 perl Porting/acknowledgements.pl v5.31.1..HEAD
8424e368 416
44691e6f
AB
417=head1 Reporting Bugs
418
373fec1e 419If you find what you think is a bug, you might check the perl bug database
15f62f05
KE
420at L<https://rt.perl.org/>. There may also be information at
421L<http://www.perl.org/>, the Perl Home Page.
44691e6f 422
e08634c5
SH
423If you believe you have an unreported bug, please run the L<perlbug> program
424included with your release. Be sure to trim your bug down to a tiny but
425sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 426will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 427
87c118b9
DM
428If the bug you are reporting has security implications which make it
429inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
430L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
431for details of how to report the issue.
44691e6f 432
390ae6f9
S
433=head1 Give Thanks
434
373fec1e
SH
435If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
436you can do so by running the C<perlthanks> program:
390ae6f9
S
437
438 perlthanks
439
440This will send an email to the Perl 5 Porters list with your show of thanks.
441
44691e6f
AB
442=head1 SEE ALSO
443
e08634c5
SH
444The F<Changes> file for an explanation of how to view exhaustive details on
445what changed.
44691e6f
AB
446
447The F<INSTALL> file for how to build Perl.
448
449The F<README> file for general stuff.
450
451The F<Artistic> and F<Copying> files for copyright information.
452
453=cut