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