This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
(perl #134125) make no digits after 0x/0b fatal
[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
dad02c36 371XXX
5b2f1ba6 372
dad02c36 373=back
5b2f1ba6 374
dad02c36 375=head1 Known Problems
5b2f1ba6 376
dad02c36
KE
377XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
378tests that had to be C<TODO>ed for the release would be noted here. Unfixed
379platform specific bugs also go here.
0367cc1a 380
dad02c36 381[ List each fix as an =item entry ]
0367cc1a 382
dad02c36 383=over 4
84ab3b69 384
fa068f6d
TC
385=item *
386
dad02c36 387XXX
fa068f6d 388
8424e368
S
389=back
390
dad02c36 391=head1 Errata From Previous Releases
8424e368 392
dad02c36 393=over 4
a0348300 394
dad02c36 395=item *
a0348300 396
dad02c36
KE
397XXX Add anything here that we forgot to add, or were mistaken about, in
398the perldelta of a previous release.
a0348300 399
dad02c36 400=back
a0348300 401
dad02c36
KE
402=head1 Obituary
403
404XXX If any significant core contributor or member of the CPAN community has
405died, add a short obituary here.
406
407=head1 Acknowledgements
a0348300 408
dad02c36 409XXX Generate this with:
8424e368 410
dad02c36 411 perl Porting/acknowledgements.pl v5.31.1..HEAD
8424e368 412
44691e6f
AB
413=head1 Reporting Bugs
414
373fec1e 415If you find what you think is a bug, you might check the perl bug database
15f62f05
KE
416at L<https://rt.perl.org/>. There may also be information at
417L<http://www.perl.org/>, the Perl Home Page.
44691e6f 418
e08634c5
SH
419If you believe you have an unreported bug, please run the L<perlbug> program
420included with your release. Be sure to trim your bug down to a tiny but
421sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 422will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 423
87c118b9
DM
424If the bug you are reporting has security implications which make it
425inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
426L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
427for details of how to report the issue.
44691e6f 428
390ae6f9
S
429=head1 Give Thanks
430
373fec1e
SH
431If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
432you can do so by running the C<perlthanks> program:
390ae6f9
S
433
434 perlthanks
435
436This will send an email to the Perl 5 Porters list with your show of thanks.
437
44691e6f
AB
438=head1 SEE ALSO
439
e08634c5
SH
440The F<Changes> file for an explanation of how to view exhaustive details on
441what changed.
44691e6f
AB
442
443The F<INSTALL> file for how to build Perl.
444
445The F<README> file for general stuff.
446
447The F<Artistic> and F<Copying> files for copyright information.
448
449=cut