This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
bump $File::Find::VERSION
[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
48=head1 Deprecations
49
50XXX Any deprecated features, syntax, modules etc. should be listed here.
51
52=head2 Module removals
53
54XXX Remove this section if not applicable.
55
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.
60
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.
64
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.
69
70=over
71
72=item XXX
73
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.
76
77=back
78
79[ List each other deprecation as a =head2 entry ]
80
81=head1 Performance Enhancements
82
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
85
86[ List each enhancement as an =item entry ]
a0348300 87
9c600b76 88=over 4
a0348300 89
9c600b76 90=item *
a0348300 91
9064626f 92XXX
a0348300 93
9064626f 94=back
9c600b76 95
9064626f 96=head1 Modules and Pragmata
a0348300 97
9064626f
SH
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
9064626f
SH
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
9064626f
SH
110[ Within each section, list entries as an =item entry ]
111
112=head2 New Modules and Pragmata
a0348300 113
9064626f 114=over 4
dad02c36 115
9c600b76
SH
116=item *
117
9064626f 118XXX Remove this section if not applicable.
a0348300 119
9064626f 120=back
a0348300 121
9064626f
SH
122=head2 Updated Modules and Pragmata
123
124=over 4
a0348300 125
9c600b76 126=item *
a0348300 127
36bb8f68
JK
128L<Thread> has been upgraded from version 3.04 to 3.05.
129
130=item *
131
9064626f
SH
132L<XXX> has been upgraded from version A.xx to B.yy.
133
134If there was something important to note about this change, include that here.
135
136=back
137
138=head2 Removed Modules and Pragmata
139
140=over 4
dad02c36 141
9c600b76 142=item *
dad02c36 143
9064626f
SH
144XXX
145
146=back
147
148=head1 Documentation
149
150XXX Changes to files in F<pod/> go here. Consider grouping entries by
151file and be sure to link to the appropriate page, e.g. L<perlfunc>.
152
153=head2 New Documentation
154
155XXX Changes which create B<new> files in F<pod/> go here.
156
157=head3 L<XXX>
158
159XXX Description of the purpose of the new file here
160
161=head2 Changes to Existing Documentation
162
163We have attempted to update the documentation to reflect the changes
164listed in this document. If you find any we have missed, send email
165to L<perlbug@perl.org|mailto:perlbug@perl.org>.
166
167XXX Changes which significantly change existing files in F<pod/> go here.
168However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
169section.
170
171Additionally, the following selected changes have been made:
172
173=head3 L<XXX>
174
175=over 4
cc1cbb06
TC
176
177=item *
178
9064626f 179XXX Description of the change here
8424e368 180
dad02c36 181=back
a0348300 182
dad02c36 183=head1 Diagnostics
a0348300 184
9064626f
SH
185The following additions or changes have been made to diagnostic output,
186including warnings and fatal error messages. For the complete list of
187diagnostic messages, see L<perldiag>.
188
189XXX New or changed warnings emitted by the core's C<C> code go here. Also
190include any changes in L<perldiag> that reconcile it to the C<C> code.
191
dad02c36 192=head2 New Diagnostics
8424e368 193
9064626f
SH
194XXX Newly added diagnostic messages go under here, separated into New Errors
195and New Warnings
196
dad02c36 197=head3 New Errors
8424e368
S
198
199=over 4
200
201=item *
202
9064626f 203XXX L<message|perldiag/"message">
8424e368 204
9064626f
SH
205=back
206
207=head3 New Warnings
208
209=over 4
210
211=item *
212
213XXX L<message|perldiag/"message">
8424e368 214
dad02c36
KE
215=back
216
217=head2 Changes to Existing Diagnostics
218
9064626f
SH
219XXX Changes (i.e. rewording) of diagnostic messages go here
220
860a458f
KE
221=over 4
222
223=item *
224
9064626f
SH
225XXX Describe change here
226
227=back
228
229=head1 Utility Changes
230
231XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
232Most of these are built within the directory F<utils>.
233
234[ List utility changes as a =head2 entry for each utility and =item
235entries for each change
236Use L<XXX> with program names to get proper documentation linking. ]
237
238=head2 L<XXX>
239
240=over 4
241
242=item *
1a7108fe 243
9064626f 244XXX
860a458f
KE
245
246=back
247
8424e368
S
248=head1 Configuration and Compilation
249
9064626f
SH
250XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
251go here. Any other changes to the Perl build process should be listed here.
252However, any platform-specific changes should be listed in the
253L</Platform Support> section, instead.
254
255[ List changes as an =item entry ].
256
8424e368
S
257=over 4
258
259=item *
260
9064626f
SH
261XXX
262
263=back
264
265=head1 Testing
266
267XXX Any significant changes to the testing of a freshly built perl should be
268listed here. Changes which create B<new> files in F<t/> go here as do any
269large changes to the testing harness (e.g. when parallel testing was added).
270Changes to existing files in F<t/> aren't worth summarizing, although the bugs
271that they represent may be covered elsewhere.
272
273XXX If there were no significant test changes, say this:
274
275Tests were added and changed to reflect the other additions and changes
276in this release.
277
278XXX If instead there were significant changes, say this:
279
280Tests were added and changed to reflect the other additions and
281changes in this release. Furthermore, these significant changes were
282made:
283
284[ List each test improvement as an =item entry ]
285
286=over 4
8424e368 287
86b50d93
DIM
288=item *
289
9064626f 290XXX
86b50d93 291
8424e368
S
292=back
293
dad02c36 294=head1 Platform Support
8424e368 295
9064626f 296XXX Any changes to platform support should be listed in the sections below.
fef47ada 297
9064626f
SH
298[ Within the sections, list each platform as an =item entry with specific
299changes as paragraphs below it. ]
4ec3954c 300
9064626f 301=head2 New Platforms
ec121dac 302
9064626f
SH
303XXX List any platforms that this version of perl compiles on, that previous
304versions did not. These will either be enabled by new files in the F<hints/>
305directories, or new subdirectories and F<README> files at the top level of the
306source tree.
ec121dac 307
9064626f 308=over 4
4ec3954c 309
9064626f
SH
310=item XXX-some-platform
311
312XXX
4ec3954c 313
dad02c36 314=back
4ec3954c 315
9064626f 316=head2 Discontinued Platforms
4ec3954c 317
9064626f 318XXX List any platforms that this version of perl no longer compiles on.
4ec3954c 319
9064626f 320=over 4
4ec3954c 321
9064626f 322=item XXX-some-platform
4ec3954c 323
9064626f 324XXX
b870557c 325
9064626f 326=back
b870557c 327
9064626f 328=head2 Platform-Specific Notes
ed0cf058 329
9064626f
SH
330XXX List any changes for specific platforms. This could include configuration
331and compilation changes or changes in portability/compatibility. However,
332changes within modules for platforms should generally be listed in the
333L</Modules and Pragmata> section.
ed0cf058 334
9064626f 335=over 4
f7faf2ad 336
9064626f 337=item XXX-some-platform
f7faf2ad 338
9064626f 339XXX
f7faf2ad 340
4ec3954c
TC
341=back
342
9064626f 343=head1 Internal Changes
4ec3954c 344
9064626f
SH
345XXX Changes which affect the interface available to C<XS> code go here. Other
346significant internal changes for future core maintainers should be noted as
347well.
2dd5ef16 348
9064626f 349[ List each change as an =item entry ]
5b2f1ba6 350
9064626f 351=over 4
5b2f1ba6 352
b870557c
TC
353=item *
354
9064626f 355XXX
b870557c 356
9064626f 357=back
ed0cf058 358
9064626f 359=head1 Selected Bug Fixes
ed0cf058 360
9064626f
SH
361XXX Important bug fixes in the core language are summarized here. Bug fixes in
362files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
973ae088 363
9064626f
SH
364[ List each fix as an =item entry ]
365
366=over 4
973ae088 367
f7faf2ad
SH
368=item *
369
052ce2b8
TC
370C<< $@ = 100; die; >> now correctly propagates the 100 as an exception
371instead of ignoring it. [perl #134291]
f7faf2ad 372
dad02c36 373=back
5b2f1ba6 374
dad02c36 375=head1 Known Problems
5b2f1ba6 376
9064626f
SH
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.
84ab3b69 380
9064626f 381[ List each fix as an =item entry ]
fa068f6d 382
9064626f 383=over 4
cb561db1
SH
384
385=item *
386
9064626f 387XXX
fa068f6d 388
8424e368
S
389=back
390
9064626f
SH
391=head1 Errata From Previous Releases
392
393=over 4
a0348300 394
9064626f
SH
395=item *
396
397XXX Add anything here that we forgot to add, or were mistaken about, in
398the perldelta of a previous release.
8424e368 399
9064626f 400=back
a01eaaa1 401
9064626f 402=head1 Obituary
a01eaaa1 403
9064626f
SH
404XXX If any significant core contributor or member of the CPAN community has
405died, add a short obituary here.
a01eaaa1 406
9064626f 407=head1 Acknowledgements
a01eaaa1 408
9064626f 409XXX Generate this with:
a01eaaa1 410
9064626f 411 perl Porting/acknowledgements.pl v5.31.2..HEAD
8424e368 412
44691e6f
AB
413=head1 Reporting Bugs
414
9064626f
SH
415If you find what you think is a bug, you might check the perl bug database
416at L<https://rt.perl.org/>. There may also be information at
15f62f05 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
9064626f
SH
426L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
427for details of how to report the issue.
44691e6f 428
390ae6f9
S
429=head1 Give Thanks
430
9064626f
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