This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix ordering of modules and pragmata in perldelta.pod
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
12dcbffb
AP
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.19.3
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
12dcbffb 12This document describes differences between the 5.19.2 release and the 5.19.3
e08634c5 13release.
6db9054f 14
12dcbffb
AP
15If you are upgrading from an earlier release such as 5.19.1, first read
16L<perl5192delta>, which describes differences between 5.19.1 and 5.19.2.
42bff0d9 17
12dcbffb 18=head1 Notice
42bff0d9 19
12dcbffb 20XXX Any important notices here
42bff0d9 21
12dcbffb 22=head1 Core Enhancements
c0ca71c9 23
12dcbffb
AP
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.
c0ca71c9 27
12dcbffb 28[ List each enhancement as a =head2 entry ]
c0ca71c9 29
5bb43e77
TC
30=head2 B<-F> now implies B<-a> and B<-a> implies B<-n>
31
32Previously B<-F> without B<-a> was a no-op, and B<-a> without B<-n> or
33B<-p> was a no-op, with this change, if you supply B<-F> then both
34B<-a> and B<-n> are implied and if you supply B<-a> then B<-n> is implied.
35
36You can still use B<-p> for its extra behaviour. [perl #116190]
37
12dcbffb 38=head1 Security
c0ca71c9 39
12dcbffb
AP
40XXX Any security-related notices go here. In particular, any security
41vulnerabilities closed should be noted here rather than in the
42L</Selected Bug Fixes> section.
c0ca71c9 43
12dcbffb 44[ List each security issue as a =head2 entry ]
c0ca71c9 45
12dcbffb 46=head1 Incompatible Changes
c0ca71c9 47
12dcbffb 48XXX For a release on a stable branch, this section aspires to be:
c0ca71c9 49
12dcbffb
AP
50 There are no changes intentionally incompatible with 5.XXX.XXX
51 If any exist, they are bugs, and we request that you submit a
52 report. See L</Reporting Bugs> below.
c0ca71c9 53
12dcbffb 54[ List each incompatible change as a =head2 entry ]
c0ca71c9 55
12dcbffb 56=head1 Deprecations
c0ca71c9 57
12dcbffb 58XXX Any deprecated features, syntax, modules etc. should be listed here.
c0ca71c9 59
12dcbffb 60=head2 Module removals
c0ca71c9 61
12dcbffb 62XXX Remove this section if inapplicable.
c0ca71c9 63
12dcbffb
AP
64The following modules will be removed from the core distribution in a
65future release, and will at that time need to be installed from CPAN.
66Distributions on CPAN which require these modules will need to list them as
67prerequisites.
c0ca71c9 68
12dcbffb
AP
69The core versions of these modules will now issue C<"deprecated">-category
70warnings to alert you to this fact. To silence these deprecation warnings,
71install the modules in question from CPAN.
c0ca71c9 72
12dcbffb
AP
73Note that these are (with rare exceptions) fine modules that you are encouraged
74to continue to use. Their disinclusion from core primarily hinges on their
75necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
76not usually on concerns over their design.
c0ca71c9 77
12dcbffb 78=over
c0ca71c9 79
12dcbffb
AP
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.
c0ca71c9 82
12dcbffb 83=back
c0ca71c9 84
12dcbffb 85[ List each other deprecation as a =head2 entry ]
c0ca71c9 86
12dcbffb 87=head1 Performance Enhancements
c0ca71c9 88
12dcbffb
AP
89XXX Changes which enhance performance without changing behaviour go here.
90There may well be none in a stable release.
c0ca71c9 91
12dcbffb 92[ List each enhancement as a =item entry ]
c0ca71c9 93
12dcbffb 94=over 4
c0ca71c9
AP
95
96=item *
97
12dcbffb 98XXX
c0ca71c9 99
12dcbffb 100=back
70ba8092 101
12dcbffb 102=head1 Modules and Pragmata
42bff0d9 103
12dcbffb
AP
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>, which prints stub
107entries to STDOUT. Results can be pasted in place of the '=head2' entries
108below. A paragraph summary for important changes should then be added by hand.
109In an ideal world, dual-life modules would have a F<Changes> file that could be
110cribbed.
6e4979f3 111
12dcbffb 112[ Within each section, list entries as a =item entry ]
6e4979f3 113
12dcbffb 114=head2 New Modules and Pragmata
6e4979f3 115
12dcbffb 116=over 4
42bff0d9 117
c0ca71c9 118=item *
42bff0d9 119
12dcbffb 120XXX
42bff0d9 121
12dcbffb 122=back
42bff0d9 123
12dcbffb 124=head2 Updated Modules and Pragmata
42bff0d9 125
12dcbffb 126=over 4
42bff0d9 127
c0ca71c9 128=item *
42bff0d9 129
323602af
TC
130L<B> has been upgraded from version 1.44 to 1.45.
131
132Calling the C<GV> method on C<B::CV> objects created from a lexical
133sub would return nonsense, possibly crashing perl. C<GV> now returns
134C<undef> for lexical subs. [perl #118525]
135
136Added the C<NAME_HEK> method to return the name of a lexical sub.
137
138=item *
139
9a743a6d
SH
140L<bignum> has been upgraded from version 0.35 to 0.36.
141
142L<bigrat> wasn't correctly updating an internal variable when C<use>d
143with a C<lib> option.
144
145=item *
146
89e01640
SH
147L<Config::Perl::V> has been upgraded from version 0.18 to 0.19.
148
149=item *
150
cffd634c
TC
151L<Data::Dumper> has been upgraded from version 2.147 to 2.148.
152
153The compatbility of the XS implementation with the pure perl version
154under C<Useqq> has been improved. [perl #118933]
42bff0d9 155
2cf99697
TC
156=item *
157
9a743a6d
SH
158L<Exporter> has been upgraded from version 5.68 to 5.69.
159
160L<Exporter> would ignore custom C<$SIG{__WARN__}> handlers in
161C<Exporter::Heavy>. [perl #39739]
162
163=item *
164
4725e868
SH
165L<parent> has been upgraded from version 0.225 to 0.226.
166
167=item *
168
669d990b
SH
169L<Socket> has been upgraded from version 2.010 to 2.011.
170
171Handle FreeBSD (or other platforms) returning shorter AF_UNIX sockaddr
172structures due to embedded sun_len. [cpan #86613]
173
174=item *
175
2cf99697
TC
176L<Storable> has been upgraded from version 2.45 to 2.46.
177
178Avoid creating temporary objects for STORABLE_attach when they aren't
179required. [perl #118907]
180
c0ca71c9 181=back
42bff0d9 182
12dcbffb 183=head2 Removed Modules and Pragmata
dbd04185 184
38663f11 185=over 4
583aa5c2 186
1fdd5e53
KW
187=item *
188
12dcbffb 189XXX
42bff0d9 190
38663f11 191=back
42bff0d9 192
12dcbffb 193=head1 Documentation
989e4501 194
12dcbffb
AP
195XXX Changes to files in F<pod/> go here. Consider grouping entries by
196file and be sure to link to the appropriate page, e.g. L<perlfunc>.
989e4501 197
12dcbffb 198=head2 New Documentation
989e4501 199
12dcbffb 200XXX Changes which create B<new> files in F<pod/> go here.
42bff0d9 201
12dcbffb 202=head3 L<XXX>
42bff0d9 203
12dcbffb 204XXX Description of the purpose of the new file here
42bff0d9 205
12dcbffb 206=head2 Changes to Existing Documentation
42bff0d9 207
12dcbffb
AP
208XXX Changes which significantly change existing files in F<pod/> go here.
209However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
210section.
42bff0d9 211
3031ec7a 212=head3 L<perlopentut>
42bff0d9 213
38663f11 214=over 4
42bff0d9
DG
215
216=item *
217
3031ec7a
RS
218The C<open> tutorial has been completely rewriten by Tom Christiansen, and now
219focuses on covering only the basics, rather than providing a comprehensive
220reference to all things openable. This rewrite came as the result of a
221vigorous discussion on perl5-porters kicked off by a set of improvements
222written by Alexander Hartmaier to the existing C<perlopentut>. A "more than
223you ever wanted to know about C<open>" document may follow in subsequent
224versions of perl.
1fdd5e53 225
583aa5c2
RS
226=back
227
c0ca71c9
AP
228=head1 Diagnostics
229
230The following additions or changes have been made to diagnostic output,
231including warnings and fatal error messages. For the complete list of
232diagnostic messages, see L<perldiag>.
233
12dcbffb
AP
234XXX New or changed warnings emitted by the core's C<C> code go here. Also
235include any changes in L<perldiag> that reconcile it to the C<C> code.
236
c0ca71c9
AP
237=head2 New Diagnostics
238
12dcbffb
AP
239XXX Newly added diagnostic messages go under here, separated into New Errors
240and New Warnings
241
242=head3 New Errors
583aa5c2 243
38663f11 244=over 4
583aa5c2 245
b8a02ff1 246=item *
583aa5c2 247
12dcbffb 248XXX L<message|perldiag/"message">
583aa5c2 249
b8a02ff1 250=back
583aa5c2 251
12dcbffb 252=head3 New Warnings
96d496e4 253
38663f11 254=over 4
b8a02ff1
DG
255
256=item *
257
12dcbffb 258XXX L<message|perldiag/"message">
96d496e4 259
12dcbffb 260=back
1310e590 261
12dcbffb 262=head2 Changes to Existing Diagnostics
e727f86a 263
12dcbffb 264XXX Changes (i.e. rewording) of diagnostic messages go here
e727f86a 265
12dcbffb 266=over 4
e727f86a 267
81ca6d44
FC
268=item *
269
12dcbffb 270XXX Describe change here
81ca6d44 271
96d496e4
RS
272=back
273
12dcbffb 274=head1 Utility Changes
583aa5c2 275
12dcbffb
AP
276XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
277Most of these are built within the directories F<utils> and F<x2p>.
71e6aba6 278
12dcbffb
AP
279[ List utility changes as a =head3 entry for each utility and =item
280entries for each change
281Use L<XXX> with program names to get proper documentation linking. ]
d5f315e8 282
12dcbffb 283=head3 L<XXX>
e38fc308
NC
284
285=over 4
286
287=item *
288
12dcbffb 289XXX
e38fc308
NC
290
291=back
292
12dcbffb 293=head1 Configuration and Compilation
2426c394 294
12dcbffb
AP
295XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
296go here. Any other changes to the Perl build process should be listed here.
297However, any platform-specific changes should be listed in the
298L</Platform Support> section, instead.
4724da03 299
12dcbffb 300[ List changes as a =item entry ].
583aa5c2 301
38663f11 302=over 4
a34da6c4 303
12dcbffb 304=item *
a34da6c4 305
12dcbffb 306XXX
a34da6c4 307
583aa5c2
RS
308=back
309
12dcbffb 310=head1 Testing
583aa5c2 311
12dcbffb
AP
312XXX Any significant changes to the testing of a freshly built perl should be
313listed here. Changes which create B<new> files in F<t/> go here as do any
314large changes to the testing harness (e.g. when parallel testing was added).
315Changes to existing files in F<t/> aren't worth summarizing, although the bugs
316that they represent may be covered elsewhere.
1de7c8e6 317
12dcbffb 318[ List each test improvement as a =item entry ]
9c800862 319
12dcbffb 320=over 4
aaf54772 321
b7bbd8b6
FC
322=item *
323
12dcbffb 324XXX
b7bbd8b6 325
583aa5c2
RS
326=back
327
12dcbffb 328=head1 Platform Support
d7bfa554 329
12dcbffb 330XXX Any changes to platform support should be listed in the sections below.
81d3ed5a 331
12dcbffb
AP
332[ Within the sections, list each platform as a =item entry with specific
333changes as paragraphs below it. ]
81d3ed5a 334
12dcbffb 335=head2 New Platforms
0b023496 336
12dcbffb
AP
337XXX List any platforms that this version of perl compiles on, that previous
338versions did not. These will either be enabled by new files in the F<hints/>
339directories, or new subdirectories and F<README> files at the top level of the
340source tree.
0b023496 341
12dcbffb 342=over 4
e11f653d 343
12dcbffb 344=item XXX-some-platform
5e0164b2 345
12dcbffb 346XXX
5e0164b2 347
12dcbffb 348=back
e11f653d 349
12dcbffb 350=head2 Discontinued Platforms
8be8cdec 351
12dcbffb 352XXX List any platforms that this version of perl no longer compiles on.
8be8cdec 353
12dcbffb 354=over 4
07a522a5 355
12dcbffb 356=item XXX-some-platform
07a522a5 357
12dcbffb 358XXX
71b4007c 359
12dcbffb 360=back
71b4007c 361
12dcbffb 362=head2 Platform-Specific Notes
f6b1d2f5 363
12dcbffb
AP
364XXX List any changes for specific platforms. This could include configuration
365and compilation changes or changes in portability/compatibility. However,
366changes within modules for platforms should generally be listed in the
367L</Modules and Pragmata> section.
f6b1d2f5 368
12dcbffb 369=over 4
7e4f209b 370
12dcbffb 371=item XXX-some-platform
7e4f209b 372
12dcbffb 373XXX
558673e6 374
12dcbffb 375=back
558673e6 376
12dcbffb 377=head1 Internal Changes
47a7c93d 378
12dcbffb
AP
379XXX Changes which affect the interface available to C<XS> code go here. Other
380significant internal changes for future core maintainers should be noted as
381well.
47a7c93d 382
12dcbffb 383[ List each change as a =item entry ]
b5a80c26 384
12dcbffb 385=over 4
b5a80c26 386
7f1d4316
FC
387=item *
388
12dcbffb 389XXX
7f1d4316 390
12dcbffb 391=back
02bef66e 392
12dcbffb 393=head1 Selected Bug Fixes
d30fb844 394
12dcbffb
AP
395XXX Important bug fixes in the core language are summarized here. Bug fixes in
396files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
d30fb844 397
12dcbffb 398[ List each fix as a =item entry ]
21c01741 399
12dcbffb 400=over 4
21c01741 401
467582e8
FC
402=item *
403
5c24ac0b
FC
404Autovivifying a subroutine stub via C<\&$glob> started causing crashes in
405Perl 5.18.0 if the $glob was merely a copy of a real glob, i.e., a scalar
406that had had a glob assigned to it. This has been fixed [perl #119051].
467582e8 407
38663f11 408=back
d7bfa554 409
38663f11 410=head1 Known Problems
6810f0ad 411
12dcbffb
AP
412XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
413tests that had to be C<TODO>ed for the release would be noted here. Unfixed
414platform specific bugs also go here.
415
416[ List each fix as a =item entry ]
417
38663f11 418=over 4
14fd9356
FC
419
420=item *
421
12dcbffb 422XXX
0e417e4d 423
38663f11 424=back
583aa5c2 425
12dcbffb
AP
426=head1 Obituary
427
428XXX If any significant core contributor has died, we've added a short obituary
429here.
430
583aa5c2 431=head1 Acknowledgements
a75569c0 432
12dcbffb
AP
433XXX Generate this with:
434
435 perl Porting/acknowledgements.pl v5.19.2..HEAD
f5b73711 436
44691e6f
AB
437=head1 Reporting Bugs
438
e08634c5
SH
439If you find what you think is a bug, you might check the articles recently
440posted to the comp.lang.perl.misc newsgroup and the perl bug database at
441http://rt.perl.org/perlbug/ . There may also be information at
442http://www.perl.org/ , the Perl Home Page.
44691e6f 443
e08634c5
SH
444If you believe you have an unreported bug, please run the L<perlbug> program
445included with your release. Be sure to trim your bug down to a tiny but
446sufficient test case. Your bug report, along with the output of C<perl -V>,
447will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
448
449If the bug you are reporting has security implications, which make it
e08634c5
SH
450inappropriate to send to a publicly archived mailing list, then please send it
451to perl5-security-report@perl.org. This points to a closed subscription
452unarchived mailing list, which includes all the core committers, who will be
453able to help assess the impact of issues, figure out a resolution, and help
f9001595 454co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
455platforms on which Perl is supported. Please only use this address for
456security issues in the Perl core, not for modules independently distributed on
457CPAN.
44691e6f
AB
458
459=head1 SEE ALSO
460
e08634c5
SH
461The F<Changes> file for an explanation of how to view exhaustive details on
462what changed.
44691e6f
AB
463
464The F<INSTALL> file for how to build Perl.
465
466The F<README> file for general stuff.
467
468The F<Artistic> and F<Copying> files for copyright information.
469
470=cut