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