This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Test that File::stat exports stat by default, overriding the builtin.
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
e96e0834
JL
5[ this is a template for a new perldelta file. Any text flagged as
6XXX needs to be processed before release. ]
27f00e3d 7
e96e0834 8perldelta - what is new for perl v5.17.2
417a992d 9
e96e0834 10=head1 DESCRIPTION
028c8719 11
e96e0834
JL
12This document describes differences between the 5.17.1 release and
13the 5.17.2 release.
028c8719 14
e96e0834
JL
15If you are upgrading from an earlier release such as 5.17.0, first read
16L<perl5171delta>, which describes differences between 5.17.0 and
175.17.1.
028c8719 18
e96e0834 19=head1 Notice
30608892 20
e96e0834 21XXX Any important notices here
e128ab2c 22
e96e0834 23=head1 Core Enhancements
e128ab2c 24
e96e0834
JL
25XXX New core language features go here. Summarise user-visible core language
26enhancements. Particularly prominent performance optimisations could go
27here, but most should go in the L</Performance Enhancements> section.
fe3193b5 28
e96e0834 29[ List each enhancement as a =head2 entry ]
05c8f9ed 30
e96e0834 31=head1 Security
0da72d5e 32
e96e0834
JL
33XXX Any security-related notices go here. In particular, any security
34vulnerabilities closed should be noted here rather than in the
35L</Selected Bug Fixes> section.
0da72d5e 36
e96e0834 37[ List each security issue as a =head2 entry ]
0da72d5e 38
e96e0834 39=head1 Incompatible Changes
0da72d5e 40
e96e0834 41XXX For a release on a stable branch, this section aspires to be:
0da72d5e 42
e96e0834
JL
43 There are no changes intentionally incompatible with 5.XXX.XXX
44 If any exist, they are bugs, and we request that you submit a
45 report. See L</Reporting Bugs> below.
0da72d5e 46
e96e0834 47[ List each incompatible change as a =head2 entry ]
e2f0c3bb 48
e96e0834 49=head1 Deprecations
e2f0c3bb 50
e96e0834
JL
51XXX Any deprecated features, syntax, modules etc. should be listed here.
52In particular, deprecated modules should be listed here even if they are
53listed as an updated module in the L</Modules and Pragmata> section.
7d101ed1 54
e96e0834 55[ List each deprecation as a =head2 entry ]
7d101ed1 56
e96e0834 57=head1 Performance Enhancements
7d101ed1 58
e96e0834
JL
59XXX Changes which enhance performance without changing behaviour go here. There
60may well be none in a stable release.
7d101ed1 61
e96e0834 62[ List each enhancement as a =item entry ]
95ce428c 63
f9001595 64=over 4
75ff5956 65
2630d42b 66=item *
c11980ad 67
e96e0834 68XXX
53de3ff0 69
61174fb5 70=back
ef7131e9 71
61174fb5 72=head1 Modules and Pragmata
ef7131e9 73
e96e0834
JL
74XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
75go here. If Module::CoreList is updated, generate an initial draft of the
76following sections using F<Porting/corelist-perldelta.pl>, which prints stub
77entries to STDOUT. Results can be pasted in place of the '=head2' entries
78below. A paragraph summary for important changes should then be added by hand.
79In an ideal world, dual-life modules would have a F<Changes> file that could be
80cribbed.
5cefbec9 81
e96e0834 82[ Within each section, list entries as a =item entry ]
fbdb83f3 83
e96e0834 84=head2 New Modules and Pragmata
95c6c5c5 85
e96e0834 86=over 4
9331f04e
NC
87
88=item *
89
e96e0834 90XXX
95c6c5c5 91
e96e0834 92=back
ff3f295c 93
e96e0834 94=head2 Updated Modules and Pragmata
ff3f295c 95
e96e0834 96=over 4
95c6c5c5 97
95c6c5c5
JL
98=item *
99
e96e0834 100L<XXX> has been upgraded from version 0.69 to version 0.70.
c506fc7e 101
e96e0834 102=back
c506fc7e 103
e96e0834 104=head2 Removed Modules and Pragmata
c506fc7e 105
e96e0834 106=over 4
95c6c5c5 107
95c6c5c5
JL
108=item *
109
e96e0834 110XXX
95c6c5c5 111
e96e0834 112=back
95c6c5c5 113
e96e0834 114=head1 Documentation
95c6c5c5 115
e96e0834
JL
116XXX Changes to files in F<pod/> go here. Consider grouping entries by
117file and be sure to link to the appropriate page, e.g. L<perlfunc>.
95c6c5c5 118
e96e0834 119=head2 New Documentation
1c633914 120
e96e0834 121XXX Changes which create B<new> files in F<pod/> go here.
f558db2f 122
e96e0834 123=head3 L<XXX>
66aa79e2 124
e96e0834 125XXX Description of the purpose of the new file here
95c6c5c5 126
e96e0834 127=head2 Changes to Existing Documentation
95c6c5c5 128
e96e0834
JL
129XXX Changes which significantly change existing files in F<pod/> go here.
130However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
131section.
95c6c5c5 132
e96e0834 133=head3 L<XXX>
95c6c5c5 134
e96e0834 135=over 4
95c6c5c5
JL
136
137=item *
138
e96e0834 139XXX Description of the change here
95c6c5c5 140
e96e0834 141=back
95c6c5c5 142
e96e0834 143=head1 Diagnostics
95c6c5c5 144
e96e0834
JL
145The following additions or changes have been made to diagnostic output,
146including warnings and fatal error messages. For the complete list of
147diagnostic messages, see L<perldiag>.
95c6c5c5 148
e96e0834
JL
149XXX New or changed warnings emitted by the core's C<C> code go here. Also
150include any changes in L<perldiag> that reconcile it to the C<C> code.
71014848 151
e96e0834
JL
152[ Within each section, list entries as a =item entry that links to perldiag,
153 e.g.
71014848 154
e96e0834 155 =item *
95c6c5c5 156
e96e0834
JL
157 L<Invalid version object|perldiag/"Invalid version object">
158]
95c6c5c5 159
e96e0834 160=head2 New Diagnostics
95c6c5c5 161
e96e0834 162XXX Newly added diagnostic messages go here
95c6c5c5 163
e96e0834 164=head3 New Errors
95c6c5c5 165
e96e0834 166=over 4
95c6c5c5 167
95c6c5c5
JL
168=item *
169
e96e0834 170XXX L<message|perldiag/"message">
95c6c5c5 171
e96e0834 172=back
95c6c5c5 173
e96e0834 174=head3 New Warnings
95c6c5c5 175
e96e0834 176=over 4
95c6c5c5 177
95c6c5c5
JL
178=item *
179
e96e0834 180XXX L<message|perldiag/"message">
7d101ed1 181
e96e0834 182=back
d9661073 183
e96e0834 184=head2 Changes to Existing Diagnostics
95c6c5c5 185
e96e0834 186XXX Changes (i.e. rewording) of diagnostic messages go here
95c6c5c5 187
e96e0834 188=over 4
95c6c5c5
JL
189
190=item *
191
e96e0834 192XXX Describe change here
3630f57e 193
e96e0834 194=back
3630f57e 195
e96e0834 196=head1 Utility Changes
95c6c5c5 197
e96e0834
JL
198XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
199here. Most of these are built within the directories F<utils> and F<x2p>.
95c6c5c5 200
e96e0834
JL
201[ List utility changes as a =head3 entry for each utility and =item
202entries for each change
203Use L<XXX> with program names to get proper documentation linking. ]
95c6c5c5 204
e96e0834 205=head3 L<XXX>
95c6c5c5 206
e96e0834 207=over 4
95c6c5c5
JL
208
209=item *
210
e96e0834 211XXX
95c6c5c5 212
e96e0834 213=back
95c6c5c5 214
e96e0834 215=head1 Configuration and Compilation
95c6c5c5 216
e96e0834
JL
217XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
218go here. Any other changes to the Perl build process should be listed here.
219However, any platform-specific changes should be listed in the
220L</Platform Support> section, instead.
95c6c5c5 221
e96e0834 222[ List changes as a =item entry ].
95c6c5c5 223
e96e0834 224=over 4
95c6c5c5
JL
225
226=item *
227
e96e0834 228XXX
95c6c5c5 229
e96e0834 230=back
95c6c5c5 231
e96e0834 232=head1 Testing
95c6c5c5 233
e96e0834
JL
234XXX Any significant changes to the testing of a freshly built perl should be
235listed here. Changes which create B<new> files in F<t/> go here as do any
236large changes to the testing harness (e.g. when parallel testing was added).
237Changes to existing files in F<t/> aren't worth summarising, although the bugs
238that they represent may be covered elsewhere.
95c6c5c5 239
e96e0834 240[ List each test improvement as a =item entry ]
95c6c5c5 241
e96e0834 242=over 4
95c6c5c5
JL
243
244=item *
245
e96e0834 246XXX
95c6c5c5 247
61174fb5 248=back
f558db2f 249
e96e0834 250=head1 Platform Support
05c8f9ed 251
e96e0834 252XXX Any changes to platform support should be listed in the sections below.
05c8f9ed 253
e96e0834
JL
254[ Within the sections, list each platform as a =item entry with specific
255changes as paragraphs below it. ]
9dea6244 256
e96e0834 257=head2 New Platforms
9dea6244 258
e96e0834
JL
259XXX List any platforms that this version of perl compiles on, that previous
260versions did not. These will either be enabled by new files in the F<hints/>
261directories, or new subdirectories and F<README> files at the top level of the
262source tree.
7d101ed1
JL
263
264=over 4
265
e96e0834 266=item XXX-some-platform
7d101ed1 267
e96e0834 268XXX
7d101ed1
JL
269
270=back
271
e96e0834 272=head2 Discontinued Platforms
ef7131e9 273
e96e0834 274XXX List any platforms that this version of perl no longer compiles on.
4a301309
FC
275
276=over 4
277
e96e0834 278=item XXX-some-platform
8dffc0ab 279
e96e0834 280XXX
dbc84d79 281
4a301309
FC
282=back
283
61174fb5 284=head2 Platform-Specific Notes
ceb0881c 285
e96e0834
JL
286XXX List any changes for specific platforms. This could include configuration
287and compilation changes or changes in portability/compatibility. However,
288changes within modules for platforms should generally be listed in the
289L</Modules and Pragmata> section.
89cbc6b8 290
e96e0834 291=over 4
0998713f 292
e96e0834 293=item XXX-some-platform
112b6866 294
e96e0834 295XXX
112b6866 296
61174fb5 297=back
8e125188 298
61174fb5 299=head1 Internal Changes
8e125188 300
e96e0834
JL
301XXX Changes which affect the interface available to C<XS> code go here.
302Other significant internal changes for future core maintainers should
303be noted as well.
c4643160 304
e96e0834 305[ List each change as a =item entry ]
f8ef51fd 306
e96e0834 307=over 4
e128ab2c 308
e2f0c3bb
FC
309=item *
310
e96e0834 311XXX
e2f0c3bb 312
61174fb5 313=back
422287bf 314
61174fb5 315=head1 Selected Bug Fixes
2de6ba8d 316
e96e0834
JL
317XXX Important bug fixes in the core language are summarised here.
318Bug fixes in files in F<ext/> and F<lib/> are best summarised in
319L</Modules and Pragmata>.
52c4b146 320
e96e0834 321[ List each fix as a =item entry ]
e128ab2c
DM
322
323=over 4
324
325=item *
326
48895a0d
KW
327A regression introduced in v5.14.0 has been fixed, in which some calls
328to the C<re> module would clobber C<$_>.
e128ab2c
DM
329
330=back
331
e96e0834 332=head1 Known Problems
dbc84d79 333
e96e0834
JL
334XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
335tests that had to be C<TODO>ed for the release would be noted here. Unfixed
336platform specific bugs also go here.
53de3ff0 337
e96e0834 338[ List each fix as a =item entry ]
233bba44
JL
339
340=over 4
341
342=item *
343
e96e0834 344XXX
233bba44 345
e96e0834 346=back
233bba44 347
e96e0834 348=head1 Obituary
233bba44 349
e96e0834
JL
350XXX If any significant core contributor has died, we've added a short obituary
351here.
233bba44 352
61174fb5 353=head1 Acknowledgements
d5dc7001 354
e96e0834
JL
355XXX Generate this with:
356
357 perl Porting/acknowledgements.pl v5.17.1..HEAD
29cf780c 358
44691e6f
AB
359=head1 Reporting Bugs
360
361If you find what you think is a bug, you might check the articles
52deee2e 362recently posted to the comp.lang.perl.misc newsgroup and the perl
f9001595
RS
363bug database at http://rt.perl.org/perlbug/ . There may also be
364information at http://www.perl.org/ , the Perl Home Page.
44691e6f
AB
365
366If you believe you have an unreported bug, please run the L<perlbug>
52deee2e
DR
367program included with your release. Be sure to trim your bug down
368to a tiny but sufficient test case. Your bug report, along with the
369output of C<perl -V>, will be sent off to perlbug@perl.org to be
370analysed by the Perl porting team.
44691e6f
AB
371
372If the bug you are reporting has security implications, which make it
f9001595
RS
373inappropriate to send to a publicly archived mailing list, then please send
374it to perl5-security-report@perl.org. This points to a closed subscription
375unarchived mailing list, which includes
376all the core committers, who will be able
377to help assess the impact of issues, figure out a resolution, and help
378co-ordinate the release of patches to mitigate or fix the problem across all
379platforms on which Perl is supported. Please only use this address for
380security issues in the Perl core, not for modules independently
381distributed on CPAN.
44691e6f
AB
382
383=head1 SEE ALSO
384
52deee2e
DR
385The F<Changes> file for an explanation of how to view exhaustive details
386on what changed.
44691e6f
AB
387
388The F<INSTALL> file for how to build Perl.
389
390The F<README> file for general stuff.
391
392The F<Artistic> and F<Copying> files for copyright information.
393
394=cut