This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 4cedf205aa6e
[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
7d19f6a1
PM
128L<ExtUtils::Manifest> has been upgraded from version 1.64 to 1.65.
129
130The MANIFEST is now opened with C<:raw>, to prevent C<CRLF>s leaking in.
131
132=item *
133
796f59e8 134L<perl5db.pl> has been upgraded from version 1.45 to 1.46.
f7df1a8c
TC
135
136Fixed the scope level handling of the debugger's C<y> command.
aac7f82f 137
0bb39c26
TC
138=item *
139
140L<POSIX> has been upgraded from version 1.41 to 1.42.
141
142Replaced the thread-unsafe code used to prevent duplicate warning
143messages for using the isxxx() functions. [perl #122476]
144
9c97a342
PM
145=item *
146
147L<Socket> has been upgraded from version 2.014 to 2.015.
148
149Test suite updates, particularly useful for Solaris and cygwin, and
150a slight change to the pattern used for IPv4 address matching.
151
13900f93 152=back
aac7f82f 153
13900f93
A
154=head2 Removed Modules and Pragmata
155
156=over 4
aac7f82f
A
157
158=item *
159
13900f93 160XXX
aac7f82f 161
13900f93 162=back
aac7f82f 163
13900f93 164=head1 Documentation
aac7f82f 165
13900f93
A
166XXX Changes to files in F<pod/> go here. Consider grouping entries by
167file and be sure to link to the appropriate page, e.g. L<perlfunc>.
aac7f82f 168
13900f93 169=head2 New Documentation
7065301c 170
13900f93 171XXX Changes which create B<new> files in F<pod/> go here.
7065301c 172
13900f93 173=head3 L<XXX>
aac7f82f 174
13900f93 175XXX Description of the purpose of the new file here
aac7f82f 176
13900f93 177=head2 Changes to Existing Documentation
6d9b7c7c 178
13900f93
A
179XXX Changes which significantly change existing files in F<pod/> go here.
180However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
181section.
6d9b7c7c 182
13900f93 183=head3 L<XXX>
7f55cec0 184
13900f93 185=over 4
7f55cec0
SH
186
187=item *
188
13900f93 189XXX Description of the change here
aac7f82f 190
13900f93 191=back
aac7f82f 192
13900f93 193=head1 Diagnostics
091fed7c 194
13900f93
A
195The following additions or changes have been made to diagnostic output,
196including warnings and fatal error messages. For the complete list of
197diagnostic messages, see L<perldiag>.
902c1f75 198
13900f93
A
199XXX New or changed warnings emitted by the core's C<C> code go here. Also
200include any changes in L<perldiag> that reconcile it to the C<C> code.
2901561d 201
13900f93 202=head2 New Diagnostics
2901561d 203
13900f93
A
204XXX Newly added diagnostic messages go under here, separated into New Errors
205and New Warnings
206
207=head3 New Errors
4594cf53 208
13900f93 209=over 4
96dcbc37
DD
210
211=item *
212
13900f93 213XXX L<message|perldiag/"message">
7065301c 214
13900f93 215=back
58f25ac1 216
13900f93
A
217=head3 New Warnings
218
219=over 4
58f25ac1
MH
220
221=item *
222
13900f93 223XXX L<message|perldiag/"message">
5bafdaa4 224
58f25ac1
MH
225=back
226
13900f93 227=head2 Changes to Existing Diagnostics
12042f24 228
13900f93 229XXX Changes (i.e. rewording) of diagnostic messages go here
b10906fb
MH
230
231=over 4
232
233=item *
234
13900f93 235XXX Describe change here
b10906fb
MH
236
237=back
238
13900f93
A
239=head1 Utility Changes
240
241XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
242Most of these are built within the directory F<utils>.
243
244[ List utility changes as a =head2 entry for each utility and =item
245entries for each change
246Use L<XXX> with program names to get proper documentation linking. ]
247
248=head2 L<XXX>
7065301c 249
6d9b7c7c 250=over 4
7065301c 251
6d9b7c7c 252=item *
0346c3a9 253
13900f93 254XXX
7065301c 255
6d9b7c7c 256=back
0346c3a9 257
13900f93
A
258=head1 Configuration and Compilation
259
260XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
261go here. Any other changes to the Perl build process should be listed here.
262However, any platform-specific changes should be listed in the
263L</Platform Support> section, instead.
264
265[ List changes as a =item entry ].
7065301c
RS
266
267=over 4
24a38d90
RS
268
269=item *
270
13900f93 271XXX
7065301c
RS
272
273=back
274
13900f93 275=head1 Testing
6d9b7c7c 276
13900f93
A
277XXX Any significant changes to the testing of a freshly built perl should be
278listed here. Changes which create B<new> files in F<t/> go here as do any
279large changes to the testing harness (e.g. when parallel testing was added).
280Changes to existing files in F<t/> aren't worth summarizing, although the bugs
281that they represent may be covered elsewhere.
6d9b7c7c 282
13900f93 283[ List each test improvement as a =item entry ]
7065301c
RS
284
285=over 4
24a38d90
RS
286
287=item *
288
13900f93 289XXX
48867f3d 290
13900f93 291=back
28462159 292
13900f93 293=head1 Platform Support
097675bf 294
13900f93 295XXX Any changes to platform support should be listed in the sections below.
b3211734 296
13900f93
A
297[ Within the sections, list each platform as a =item entry with specific
298changes as paragraphs below it. ]
b3211734 299
13900f93 300=head2 New Platforms
24a38d90 301
13900f93
A
302XXX List any platforms that this version of perl compiles on, that previous
303versions did not. These will either be enabled by new files in the F<hints/>
304directories, or new subdirectories and F<README> files at the top level of the
305source tree.
b08d439a 306
0346c3a9 307=over 4
747b6130 308
13900f93 309=item XXX-some-platform
747b6130 310
13900f93 311XXX
7065301c
RS
312
313=back
314
13900f93
A
315=head2 Discontinued Platforms
316
317XXX List any platforms that this version of perl no longer compiles on.
0346c3a9 318
7065301c
RS
319=over 4
320
13900f93 321=item XXX-some-platform
24a38d90 322
13900f93 323XXX
7065301c
RS
324
325=back
326
7065301c
RS
327=head2 Platform-Specific Notes
328
13900f93
A
329XXX List any changes for specific platforms. This could include configuration
330and compilation changes or changes in portability/compatibility. However,
331changes within modules for platforms should generally be listed in the
332L</Modules and Pragmata> section.
333
0346c3a9 334=over 4
7d0ccdba 335
13900f93 336=item XXX-some-platform
7d0ccdba 337
13900f93 338XXX
7d0ccdba 339
7065301c
RS
340=back
341
342=head1 Internal Changes
343
13900f93
A
344XXX Changes which affect the interface available to C<XS> code go here. Other
345significant internal changes for future core maintainers should be noted as
346well.
c9fcb674 347
13900f93 348[ List each change as a =item entry ]
ddeaf645 349
13900f93 350=over 4
c9fcb674 351
a835cd47
KW
352=item *
353
d8bcb4d6
KW
354Added L<perlapi/sync_locale>.
355Changing the program's locale should be avoided by XS code. Nevertheless,
356certain non-Perl libraries called from XS, such as C<Gtk> do so. When this
357happens, Perl needs to be told that the locale has changed. Use this function
358to do so, before returning to Perl.
c1284011 359
6d9b7c7c 360=back
c1284011 361
6d9b7c7c 362=head1 Selected Bug Fixes
375f5f06 363
13900f93
A
364XXX Important bug fixes in the core language are summarized here. Bug fixes in
365files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
366
367[ List each fix as a =item entry ]
368
0346c3a9 369=over 4
375f5f06 370
2884baee
MH
371=item *
372
0dd816ae
TC
373Failing to compile C<use Foo> in an eval could leave a spurious
374C<BEGIN> subroutine definition, which would produce a "Subroutine
375BEGIN redefined" warning on the next use of C<use>, or other C<BEGIN>
376block. [perl #122107]
2884baee 377
b756670b
FC
378=item *
379
380C<method { BLOCK } ARGS> syntax now correctly parses the arguments if they
381begin with an opening brace. [perl #46947]
382
13900f93
A
383=back
384
385=head1 Known Problems
386
387XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
388tests that had to be C<TODO>ed for the release would be noted here. Unfixed
389platform specific bugs also go here.
5af51eb4 390
13900f93
A
391[ List each fix as a =item entry ]
392
393=over 4
5af51eb4 394
412f55bb
KW
395=item *
396
13900f93 397XXX
412f55bb 398
7065301c
RS
399=back
400
13900f93 401=head1 Errata From Previous Releases
24a38d90 402
13900f93
A
403=over 4
404
405=item *
e831f11a 406
13900f93
A
407XXX Add anything here that we forgot to add, or were mistaken about, in
408the perldelta of a previous release.
e831f11a 409
13900f93
A
410=back
411
412=head1 Obituary
e831f11a 413
13900f93
A
414XXX If any significant core contributor has died, we've added a short obituary
415here.
e831f11a 416
13900f93 417=head1 Acknowledgements
e831f11a 418
13900f93 419XXX Generate this with:
e831f11a 420
13900f93 421 perl Porting/acknowledgements.pl v5.21.2..HEAD
f5b73711 422
44691e6f
AB
423=head1 Reporting Bugs
424
e08634c5
SH
425If you find what you think is a bug, you might check the articles recently
426posted to the comp.lang.perl.misc newsgroup and the perl bug database at
238894db 427https://rt.perl.org/ . There may also be information at
7ef8b31d 428http://www.perl.org/ , the Perl Home Page.
44691e6f 429
e08634c5
SH
430If you believe you have an unreported bug, please run the L<perlbug> program
431included with your release. Be sure to trim your bug down to a tiny but
432sufficient test case. Your bug report, along with the output of C<perl -V>,
433will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
434
435If the bug you are reporting has security implications, which make it
e08634c5
SH
436inappropriate to send to a publicly archived mailing list, then please send it
437to perl5-security-report@perl.org. This points to a closed subscription
438unarchived mailing list, which includes all the core committers, who will be
439able to help assess the impact of issues, figure out a resolution, and help
f9001595 440co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
441platforms on which Perl is supported. Please only use this address for
442security issues in the Perl core, not for modules independently distributed on
443CPAN.
44691e6f
AB
444
445=head1 SEE ALSO
446
e08634c5
SH
447The F<Changes> file for an explanation of how to view exhaustive details on
448what changed.
44691e6f
AB
449
450The F<INSTALL> file for how to build Perl.
451
452The F<README> file for general stuff.
453
454The F<Artistic> and F<Copying> files for copyright information.
455
456=cut