This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for removing experimental status
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
46a21c0a
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.6
d407e309 9
862f380b 10=head1 DESCRIPTION
261e14b0 11
46a21c0a 12This document describes differences between the 5.31.5 release and the 5.31.6
862f380b 13release.
261e14b0 14
46a21c0a
SH
15If you are upgrading from an earlier release such as 5.31.4, first read
16L<perl5315delta>, which describes differences between 5.31.4 and 5.31.5.
17
18=head1 Notice
19
cbc4b0d0 20XXX Any important notices here.
46a21c0a
SH
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
b16dfd16
KW
30=head2 Alpha assertions are no longer experimental
31
32See L<perlre/(*pla:pattern)>, L<perlre/(*plb:pattern)>,
33L<perlre/(*nla:pattern)>>, and L<perlre/(*nlb:pattern)>.
34Use of these no longer generates a warning; existing code that disables
35the warning category C<experimental::script_run> will continue to work
36without any changes needed. Enabling the category has no effect.
37
38=head2 Script runs are no longer experimental
39
40See L<perlre/Script Runs>. Use of these no longer generates a warning;
41existing code that disables the warning category
42C<experimental::alpha_assertions> will continue to work without any
43changes needed. Enabling the category has no effect.
44
46a21c0a
SH
45=head1 Security
46
47XXX Any security-related notices go here. In particular, any security
48vulnerabilities closed should be noted here rather than in the
49L</Selected Bug Fixes> section.
50
51[ List each security issue as a =head2 entry ]
fcbec156 52
9064626f
SH
53=head1 Incompatible Changes
54
46a21c0a 55XXX For a release on a stable branch, this section aspires to be:
7fd0eed3 56
46a21c0a
SH
57 There are no changes intentionally incompatible with 5.XXX.XXX
58 If any exist, they are bugs, and we request that you submit a
59 report. See L</Reporting Bugs> below.
7fd0eed3 60
46a21c0a 61[ List each incompatible change as a =head2 entry ]
7fd0eed3 62
46a21c0a 63=head1 Deprecations
7fd0eed3 64
46a21c0a 65XXX Any deprecated features, syntax, modules etc. should be listed here.
7fd0eed3 66
46a21c0a 67=head2 Module removals
7fd0eed3 68
46a21c0a 69XXX Remove this section if not applicable.
7fd0eed3 70
46a21c0a
SH
71The following modules will be removed from the core distribution in a
72future release, and will at that time need to be installed from CPAN.
73Distributions on CPAN which require these modules will need to list them as
74prerequisites.
7fd0eed3 75
46a21c0a
SH
76The core versions of these modules will now issue C<"deprecated">-category
77warnings to alert you to this fact. To silence these deprecation warnings,
78install the modules in question from CPAN.
be2eb09e 79
46a21c0a
SH
80Note that these are (with rare exceptions) fine modules that you are encouraged
81to continue to use. Their disinclusion from core primarily hinges on their
82necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
83not usually on concerns over their design.
03b7d279 84
46a21c0a 85=over
03b7d279 86
46a21c0a 87=item XXX
03b7d279 88
46a21c0a
SH
89XXX Note that deprecated modules should be listed here even if they are listed
90as an updated module in the L</Modules and Pragmata> section.
03b7d279 91
46a21c0a 92=back
74c14c97 93
46a21c0a 94[ List each other deprecation as a =head2 entry ]
36bb8f68 95
46a21c0a 96=head1 Performance Enhancements
36bb8f68 97
46a21c0a
SH
98XXX Changes which enhance performance without changing behaviour go here.
99There may well be none in a stable release.
c8d86fdc 100
46a21c0a 101[ List each enhancement as an =item entry ]
ced2c819 102
46a21c0a 103=over 4
74c14c97 104
eeef80ee
JK
105=item *
106
46a21c0a 107XXX
eeef80ee 108
46a21c0a 109=back
eeef80ee 110
46a21c0a 111=head1 Modules and Pragmata
c8d86fdc 112
46a21c0a
SH
113XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
114go here. If Module::CoreList is updated, generate an initial draft of the
115following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
116for important changes should then be added by hand. In an ideal world,
117dual-life modules would have a F<Changes> file that could be cribbed.
74c14c97 118
46a21c0a
SH
119The list of new and updated modules is modified automatically as part of
120preparing a Perl release, so the only reason to manually add entries here is if
121you're summarising the important changes in the module update. (Also, if the
122manually-added details don't match the automatically-generated ones, the
123release manager will have to investigate the situation carefully.)
ced2c819 124
46a21c0a 125[ Within each section, list entries as an =item entry ]
be2eb09e 126
46a21c0a 127=head2 New Modules and Pragmata
be2eb09e 128
46a21c0a 129=over 4
ced2c819
SH
130
131=item *
132
46a21c0a 133XXX Remove this section if not applicable.
ced2c819 134
46a21c0a
SH
135=back
136
137=head2 Updated Modules and Pragmata
ced2c819 138
46a21c0a 139=over 4
ced2c819
SH
140
141=item *
142
46a21c0a 143L<XXX> has been upgraded from version A.xx to B.yy.
ced2c819 144
46a21c0a
SH
145If there was something important to note about this change, include that here.
146
1945661d
JK
147=item *
148
149L<Sys::Syslog> has been upgraded from version 0.35 to 0.36.
150
46a21c0a 151=back
ced2c819 152
46a21c0a
SH
153=head2 Removed Modules and Pragmata
154
155=over 4
ced2c819
SH
156
157=item *
158
46a21c0a 159XXX
ced2c819 160
fcbec156
TH
161=back
162
74c14c97
MM
163=head1 Documentation
164
46a21c0a
SH
165XXX Changes to files in F<pod/> go here. Consider grouping entries by
166file and be sure to link to the appropriate page, e.g. L<perlfunc>.
167
168=head2 New Documentation
169
170XXX Changes which create B<new> files in F<pod/> go here.
171
172=head3 L<XXX>
173
174XXX Description of the purpose of the new file here
175
fcbec156
TH
176=head2 Changes to Existing Documentation
177
46a21c0a
SH
178We have attempted to update the documentation to reflect the changes
179listed in this document. If you find any we have missed, send email
180to L<perlbug@perl.org|mailto:perlbug@perl.org>.
181
182XXX Changes which significantly change existing files in F<pod/> go here.
183However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
184section.
fcbec156 185
46a21c0a
SH
186Additionally, the following selected changes have been made:
187
188=head3 L<XXX>
336e728b
SH
189
190=over 4
191
192=item *
193
46a21c0a 194XXX Description of the change here
336e728b
SH
195
196=back
74c14c97 197
46a21c0a 198=head1 Diagnostics
fcbec156 199
46a21c0a
SH
200The following additions or changes have been made to diagnostic output,
201including warnings and fatal error messages. For the complete list of
202diagnostic messages, see L<perldiag>.
04d3d25b 203
46a21c0a
SH
204XXX New or changed warnings emitted by the core's C<C> code go here. Also
205include any changes in L<perldiag> that reconcile it to the C<C> code.
04d3d25b 206
46a21c0a 207=head2 New Diagnostics
04d3d25b 208
46a21c0a
SH
209XXX Newly added diagnostic messages go under here, separated into New Errors
210and New Warnings
04d3d25b 211
46a21c0a 212=head3 New Errors
04d3d25b 213
46a21c0a 214=over 4
04d3d25b
MM
215
216=item *
217
46a21c0a 218XXX L<message|perldiag/"message">
04d3d25b
MM
219
220=back
221
46a21c0a 222=head3 New Warnings
fcbec156 223
46a21c0a
SH
224=over 4
225
226=item *
227
228XXX L<message|perldiag/"message">
229
230=back
fcbec156 231
336e728b 232=head2 Changes to Existing Diagnostics
74c14c97 233
46a21c0a
SH
234XXX Changes (i.e. rewording) of diagnostic messages go here
235
74c14c97
MM
236=over 4
237
238=item *
239
46a21c0a 240XXX Describe change here
74c14c97 241
46a21c0a 242=back
74c14c97 243
46a21c0a 244=head1 Utility Changes
74c14c97 245
46a21c0a
SH
246XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
247Most of these are built within the directory F<utils>.
74c14c97 248
46a21c0a
SH
249[ List utility changes as a =head2 entry for each utility and =item
250entries for each change
251Use L<XXX> with program names to get proper documentation linking. ]
74c14c97 252
46a21c0a
SH
253=head2 L<XXX>
254
255=over 4
256
257=item *
258
259XXX
913b4d0b 260
74c14c97
MM
261=back
262
fcbec156
TH
263=head1 Configuration and Compilation
264
46a21c0a
SH
265XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
266go here. Any other changes to the Perl build process should be listed here.
267However, any platform-specific changes should be listed in the
268L</Platform Support> section, instead.
269
270[ List changes as an =item entry ].
271
fcbec156 272=over 4
f0f66070
TC
273
274=item *
275
46a21c0a 276XXX
06bfb2b1 277
46a21c0a
SH
278=back
279
280=head1 Testing
281
282XXX Any significant changes to the testing of a freshly built perl should be
283listed here. Changes which create B<new> files in F<t/> go here as do any
284large changes to the testing harness (e.g. when parallel testing was added).
285Changes to existing files in F<t/> aren't worth summarizing, although the bugs
286that they represent may be covered elsewhere.
287
288XXX If there were no significant test changes, say this:
289
290Tests were added and changed to reflect the other additions and changes
291in this release.
292
293XXX If instead there were significant changes, say this:
294
295Tests were added and changed to reflect the other additions and
296changes in this release. Furthermore, these significant changes were
297made:
c5103e52 298
46a21c0a
SH
299[ List each test improvement as an =item entry ]
300
301=over 4
c5103e52
MB
302
303=item *
304
46a21c0a 305XXX
c5103e52 306
fcbec156
TH
307=back
308
46a21c0a 309=head1 Platform Support
fcbec156 310
46a21c0a 311XXX Any changes to platform support should be listed in the sections below.
fcbec156 312
46a21c0a
SH
313[ Within the sections, list each platform as an =item entry with specific
314changes as paragraphs below it. ]
8424e368 315
46a21c0a
SH
316=head2 New Platforms
317
318XXX List any platforms that this version of perl compiles on, that previous
319versions did not. These will either be enabled by new files in the F<hints/>
320directories, or new subdirectories and F<README> files at the top level of the
321source tree.
fcbec156 322
74c14c97 323=over 4
0076a047 324
46a21c0a 325=item XXX-some-platform
74c14c97 326
46a21c0a 327XXX
feedae7a 328
46a21c0a 329=back
feedae7a 330
46a21c0a 331=head2 Discontinued Platforms
fcbec156 332
46a21c0a 333XXX List any platforms that this version of perl no longer compiles on.
feedae7a 334
46a21c0a
SH
335=over 4
336
337=item XXX-some-platform
338
339XXX
feedae7a
SH
340
341=back
342
46a21c0a
SH
343=head2 Platform-Specific Notes
344
345XXX List any changes for specific platforms. This could include configuration
346and compilation changes or changes in portability/compatibility. However,
347changes within modules for platforms should generally be listed in the
348L</Modules and Pragmata> section.
349
350=over 4
351
352=item XXX-some-platform
353
354XXX
355
fcbec156
TH
356=back
357
358=head1 Internal Changes
359
46a21c0a
SH
360XXX Changes which affect the interface available to C<XS> code go here. Other
361significant internal changes for future core maintainers should be noted as
362well.
363
364[ List each change as an =item entry ]
365
fcbec156 366=over 4
061637ca 367
285db695
DM
368=item *
369
46a21c0a
SH
370XXX
371
372=back
373
374=head1 Selected Bug Fixes
375
376XXX Important bug fixes in the core language are summarized here. Bug fixes in
377files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
378
379[ List each fix as an =item entry ]
380
381=over 4
285db695 382
059703b0
KW
383=item *
384
46a21c0a 385XXX
059703b0 386
9064626f 387=back
ed0cf058 388
46a21c0a 389=head1 Known Problems
bd833cba 390
46a21c0a
SH
391XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
392tests that had to be C<TODO>ed for the release would be noted here. Unfixed
393platform specific bugs also go here.
bd833cba 394
46a21c0a 395[ List each fix as an =item entry ]
f3d30b53 396
46a21c0a
SH
397=over 4
398
399=item *
400
401XXX
402
403=back
404
405=head1 Errata From Previous Releases
406
407=over 4
408
409=item *
410
411XXX Add anything here that we forgot to add, or were mistaken about, in
412the perldelta of a previous release.
f3d30b53 413
46a21c0a
SH
414=back
415
416=head1 Obituary
f3d30b53 417
46a21c0a
SH
418XXX If any significant core contributor or member of the CPAN community has
419died, add a short obituary here.
420
421=head1 Acknowledgements
f3d30b53 422
46a21c0a 423XXX Generate this with:
f3d30b53 424
46a21c0a 425 perl Porting/acknowledgements.pl v5.31.5..HEAD
8424e368 426
44691e6f
AB
427=head1 Reporting Bugs
428
46a21c0a
SH
429If you find what you think is a bug, you might check the perl bug database
430at L<https://rt.perl.org/>. There may also be information at
431L<http://www.perl.org/>, the Perl Home Page.
44691e6f 432
e08634c5
SH
433If you believe you have an unreported bug, please run the L<perlbug> program
434included with your release. Be sure to trim your bug down to a tiny but
435sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 436will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 437
87c118b9
DM
438If the bug you are reporting has security implications which make it
439inappropriate to send to a publicly archived mailing list, then see
46a21c0a
SH
440L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
441for details of how to report the issue.
44691e6f 442
390ae6f9
S
443=head1 Give Thanks
444
46a21c0a
SH
445If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
446you can do so by running the C<perlthanks> program:
390ae6f9
S
447
448 perlthanks
449
450This will send an email to the Perl 5 Porters list with your show of thanks.
451
44691e6f
AB
452=head1 SEE ALSO
453
e08634c5
SH
454The F<Changes> file for an explanation of how to view exhaustive details on
455what changed.
44691e6f
AB
456
457The F<INSTALL> file for how to build Perl.
458
459The F<README> file for general stuff.
460
461The F<Artistic> and F<Copying> files for copyright information.
462
463=cut