This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #122107] ensure that BEGIN blocks with errors don't remain named subs
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
13900f93
A
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.21.3
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
13900f93 12This document describes differences between the 5.21.2 release and the 5.21.3
238894db 13release.
c68523cb 14
13900f93
A
15If you are upgrading from an earlier release such as 5.21.1, first read
16L<perl5212delta>, which describes differences between 5.21.1 and 5.21.2.
17
18=head1 Notice
19
20XXX Any important notices here
7065301c 21
7065301c
RS
22=head1 Core Enhancements
23
13900f93
A
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.
7e957246 27
13900f93 28[ List each enhancement as a =head2 entry ]
7e957246 29
0346c3a9 30=head1 Security
7e957246 31
13900f93
A
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 ]
8bdb3f93 37
13900f93 38=head1 Incompatible Changes
8bdb3f93 39
13900f93 40XXX For a release on a stable branch, this section aspires to be:
8bdb3f93 41
13900f93
A
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 ]
cd209d9d 47
1178d2cf
DIM
48=head2 S<C<use UNIVERSAL '...'>> is now a fatal error
49
50Importing functions from C<UNIVERSAL> has been deprecated since v5.12, and
51is now a fatal error. S<C<"use UNIVERSAL">> without any arguments is still
52allowed.
53
0346c3a9 54=head1 Deprecations
5320b60d 55
13900f93 56XXX Any deprecated features, syntax, modules etc. should be listed here.
36304e49 57
13900f93 58=head2 Module removals
7065301c 59
13900f93 60XXX Remove this section if inapplicable.
df758df2 61
13900f93
A
62The following modules will be removed from the core distribution in a
63future release, and will at that time need to be installed from CPAN.
64Distributions on CPAN which require these modules will need to list them as
65prerequisites.
df758df2 66
13900f93
A
67The core versions of these modules will now issue C<"deprecated">-category
68warnings to alert you to this fact. To silence these deprecation warnings,
69install the modules in question from CPAN.
412f55bb 70
13900f93
A
71Note that these are (with rare exceptions) fine modules that you are encouraged
72to continue to use. Their disinclusion from core primarily hinges on their
73necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
74not usually on concerns over their design.
412f55bb 75
13900f93 76=over
7065301c 77
13900f93 78=item XXX
7065301c 79
13900f93
A
80XXX Note that deprecated modules should be listed here even if they are listed
81as an updated module in the L</Modules and Pragmata> section.
d133a3dd 82
13900f93
A
83=back
84
85[ List each other deprecation as a =head2 entry ]
86
87=head1 Performance Enhancements
88
89XXX Changes which enhance performance without changing behaviour go here.
90There may well be none in a stable release.
91
92[ List each enhancement as a =item entry ]
93
94=over 4
7065301c 95
6bb82be0
MH
96=item *
97
13900f93 98XXX
6bb82be0 99
7065301c
RS
100=back
101
7ef8b31d 102=head1 Modules and Pragmata
f6f3144e 103
13900f93
A
104XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
105go here. If Module::CoreList is updated, generate an initial draft of the
106following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
107for important changes should then be added by hand. In an ideal world,
108dual-life modules would have a F<Changes> file that could be cribbed.
2fc36bac 109
13900f93 110[ Within each section, list entries as a =item entry ]
2fc36bac 111
13900f93 112=head2 New Modules and Pragmata
2fc36bac 113
13900f93 114=over 4
24a38d90
RS
115
116=item *
117
13900f93 118XXX
7065301c 119
13900f93
A
120=back
121
122=head2 Updated Modules and Pragmata
7065301c 123
13900f93 124=over 4
7065301c 125
aac7f82f
A
126=item *
127
13900f93 128L<XXX> has been upgraded from version A.xx to B.yy.
aac7f82f 129
13900f93 130=back
aac7f82f 131
13900f93
A
132=head2 Removed Modules and Pragmata
133
134=over 4
aac7f82f
A
135
136=item *
137
13900f93 138XXX
aac7f82f 139
13900f93 140=back
aac7f82f 141
13900f93 142=head1 Documentation
aac7f82f 143
13900f93
A
144XXX Changes to files in F<pod/> go here. Consider grouping entries by
145file and be sure to link to the appropriate page, e.g. L<perlfunc>.
aac7f82f 146
13900f93 147=head2 New Documentation
7065301c 148
13900f93 149XXX Changes which create B<new> files in F<pod/> go here.
7065301c 150
13900f93 151=head3 L<XXX>
aac7f82f 152
13900f93 153XXX Description of the purpose of the new file here
aac7f82f 154
13900f93 155=head2 Changes to Existing Documentation
6d9b7c7c 156
13900f93
A
157XXX Changes which significantly change existing files in F<pod/> go here.
158However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
159section.
6d9b7c7c 160
13900f93 161=head3 L<XXX>
7f55cec0 162
13900f93 163=over 4
7f55cec0
SH
164
165=item *
166
13900f93 167XXX Description of the change here
aac7f82f 168
13900f93 169=back
aac7f82f 170
13900f93 171=head1 Diagnostics
091fed7c 172
13900f93
A
173The following additions or changes have been made to diagnostic output,
174including warnings and fatal error messages. For the complete list of
175diagnostic messages, see L<perldiag>.
902c1f75 176
13900f93
A
177XXX New or changed warnings emitted by the core's C<C> code go here. Also
178include any changes in L<perldiag> that reconcile it to the C<C> code.
2901561d 179
13900f93 180=head2 New Diagnostics
2901561d 181
13900f93
A
182XXX Newly added diagnostic messages go under here, separated into New Errors
183and New Warnings
184
185=head3 New Errors
4594cf53 186
13900f93 187=over 4
96dcbc37
DD
188
189=item *
190
13900f93 191XXX L<message|perldiag/"message">
7065301c 192
13900f93 193=back
58f25ac1 194
13900f93
A
195=head3 New Warnings
196
197=over 4
58f25ac1
MH
198
199=item *
200
13900f93 201XXX L<message|perldiag/"message">
5bafdaa4 202
58f25ac1
MH
203=back
204
13900f93 205=head2 Changes to Existing Diagnostics
12042f24 206
13900f93 207XXX Changes (i.e. rewording) of diagnostic messages go here
b10906fb
MH
208
209=over 4
210
211=item *
212
13900f93 213XXX Describe change here
b10906fb
MH
214
215=back
216
13900f93
A
217=head1 Utility Changes
218
219XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
220Most of these are built within the directory F<utils>.
221
222[ List utility changes as a =head2 entry for each utility and =item
223entries for each change
224Use L<XXX> with program names to get proper documentation linking. ]
225
226=head2 L<XXX>
7065301c 227
6d9b7c7c 228=over 4
7065301c 229
6d9b7c7c 230=item *
0346c3a9 231
13900f93 232XXX
7065301c 233
6d9b7c7c 234=back
0346c3a9 235
13900f93
A
236=head1 Configuration and Compilation
237
238XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
239go here. Any other changes to the Perl build process should be listed here.
240However, any platform-specific changes should be listed in the
241L</Platform Support> section, instead.
242
243[ List changes as a =item entry ].
7065301c
RS
244
245=over 4
24a38d90
RS
246
247=item *
248
13900f93 249XXX
7065301c
RS
250
251=back
252
13900f93 253=head1 Testing
6d9b7c7c 254
13900f93
A
255XXX Any significant changes to the testing of a freshly built perl should be
256listed here. Changes which create B<new> files in F<t/> go here as do any
257large changes to the testing harness (e.g. when parallel testing was added).
258Changes to existing files in F<t/> aren't worth summarizing, although the bugs
259that they represent may be covered elsewhere.
6d9b7c7c 260
13900f93 261[ List each test improvement as a =item entry ]
7065301c
RS
262
263=over 4
24a38d90
RS
264
265=item *
266
13900f93 267XXX
48867f3d 268
13900f93 269=back
28462159 270
13900f93 271=head1 Platform Support
097675bf 272
13900f93 273XXX Any changes to platform support should be listed in the sections below.
b3211734 274
13900f93
A
275[ Within the sections, list each platform as a =item entry with specific
276changes as paragraphs below it. ]
b3211734 277
13900f93 278=head2 New Platforms
24a38d90 279
13900f93
A
280XXX List any platforms that this version of perl compiles on, that previous
281versions did not. These will either be enabled by new files in the F<hints/>
282directories, or new subdirectories and F<README> files at the top level of the
283source tree.
b08d439a 284
0346c3a9 285=over 4
747b6130 286
13900f93 287=item XXX-some-platform
747b6130 288
13900f93 289XXX
7065301c
RS
290
291=back
292
13900f93
A
293=head2 Discontinued Platforms
294
295XXX List any platforms that this version of perl no longer compiles on.
0346c3a9 296
7065301c
RS
297=over 4
298
13900f93 299=item XXX-some-platform
24a38d90 300
13900f93 301XXX
7065301c
RS
302
303=back
304
7065301c
RS
305=head2 Platform-Specific Notes
306
13900f93
A
307XXX List any changes for specific platforms. This could include configuration
308and compilation changes or changes in portability/compatibility. However,
309changes within modules for platforms should generally be listed in the
310L</Modules and Pragmata> section.
311
0346c3a9 312=over 4
7d0ccdba 313
13900f93 314=item XXX-some-platform
7d0ccdba 315
13900f93 316XXX
7d0ccdba 317
7065301c
RS
318=back
319
320=head1 Internal Changes
321
13900f93
A
322XXX Changes which affect the interface available to C<XS> code go here. Other
323significant internal changes for future core maintainers should be noted as
324well.
c9fcb674 325
13900f93 326[ List each change as a =item entry ]
ddeaf645 327
13900f93 328=over 4
c9fcb674 329
a835cd47
KW
330=item *
331
13900f93 332XXX
c1284011 333
6d9b7c7c 334=back
c1284011 335
6d9b7c7c 336=head1 Selected Bug Fixes
375f5f06 337
13900f93
A
338XXX Important bug fixes in the core language are summarized here. Bug fixes in
339files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
340
341[ List each fix as a =item entry ]
342
0346c3a9 343=over 4
375f5f06 344
2884baee
MH
345=item *
346
13900f93 347XXX
2884baee 348
13900f93
A
349=back
350
351=head1 Known Problems
352
353XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
354tests that had to be C<TODO>ed for the release would be noted here. Unfixed
355platform specific bugs also go here.
5af51eb4 356
13900f93
A
357[ List each fix as a =item entry ]
358
359=over 4
5af51eb4 360
412f55bb
KW
361=item *
362
13900f93 363XXX
412f55bb 364
7065301c
RS
365=back
366
13900f93 367=head1 Errata From Previous Releases
24a38d90 368
13900f93
A
369=over 4
370
371=item *
e831f11a 372
13900f93
A
373XXX Add anything here that we forgot to add, or were mistaken about, in
374the perldelta of a previous release.
e831f11a 375
13900f93
A
376=back
377
378=head1 Obituary
e831f11a 379
13900f93
A
380XXX If any significant core contributor has died, we've added a short obituary
381here.
e831f11a 382
13900f93 383=head1 Acknowledgements
e831f11a 384
13900f93 385XXX Generate this with:
e831f11a 386
13900f93 387 perl Porting/acknowledgements.pl v5.21.2..HEAD
f5b73711 388
44691e6f
AB
389=head1 Reporting Bugs
390
e08634c5
SH
391If you find what you think is a bug, you might check the articles recently
392posted to the comp.lang.perl.misc newsgroup and the perl bug database at
238894db 393https://rt.perl.org/ . There may also be information at
7ef8b31d 394http://www.perl.org/ , the Perl Home Page.
44691e6f 395
e08634c5
SH
396If you believe you have an unreported bug, please run the L<perlbug> program
397included with your release. Be sure to trim your bug down to a tiny but
398sufficient test case. Your bug report, along with the output of C<perl -V>,
399will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
400
401If the bug you are reporting has security implications, which make it
e08634c5
SH
402inappropriate to send to a publicly archived mailing list, then please send it
403to perl5-security-report@perl.org. This points to a closed subscription
404unarchived mailing list, which includes all the core committers, who will be
405able to help assess the impact of issues, figure out a resolution, and help
f9001595 406co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
407platforms on which Perl is supported. Please only use this address for
408security issues in the Perl core, not for modules independently distributed on
409CPAN.
44691e6f
AB
410
411=head1 SEE ALSO
412
e08634c5
SH
413The F<Changes> file for an explanation of how to view exhaustive details on
414what changed.
44691e6f
AB
415
416The F<INSTALL> file for how to build Perl.
417
418The F<README> file for general stuff.
419
420The F<Artistic> and F<Copying> files for copyright information.
421
422=cut