This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add E. Choroba to AUTHORS
[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
4c77591b
NC
100L<File::stat> has been upgraded from version 1.06 to 1.07.
101
102Previously C<File::stat>'s overloaded C<-x> and C<-X> operators did not give
103the correct results for directories or executable files when running as
104root. They had been treating executable permissions for root just like for
105any other user, performing group membership tests I<etc> for files not owned
106by root. They now follow the correct Unix behaviour - for a directory they
107are always true, and for a file if any of the three execute permission bits
108are set then they report that root can execute the file. Perl's builtin
109C<-x> and C<-X> operators have always been correct.
c506fc7e 110
e96e0834 111=back
c506fc7e 112
e96e0834 113=head2 Removed Modules and Pragmata
c506fc7e 114
e96e0834 115=over 4
95c6c5c5 116
95c6c5c5
JL
117=item *
118
e96e0834 119XXX
95c6c5c5 120
e96e0834 121=back
95c6c5c5 122
e96e0834 123=head1 Documentation
95c6c5c5 124
e96e0834
JL
125XXX Changes to files in F<pod/> go here. Consider grouping entries by
126file and be sure to link to the appropriate page, e.g. L<perlfunc>.
95c6c5c5 127
e96e0834 128=head2 New Documentation
1c633914 129
e96e0834 130XXX Changes which create B<new> files in F<pod/> go here.
f558db2f 131
e96e0834 132=head3 L<XXX>
66aa79e2 133
e96e0834 134XXX Description of the purpose of the new file here
95c6c5c5 135
e96e0834 136=head2 Changes to Existing Documentation
95c6c5c5 137
e96e0834
JL
138XXX Changes which significantly change existing files in F<pod/> go here.
139However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
140section.
95c6c5c5 141
e96e0834 142=head3 L<XXX>
95c6c5c5 143
e96e0834 144=over 4
95c6c5c5
JL
145
146=item *
147
e96e0834 148XXX Description of the change here
95c6c5c5 149
e96e0834 150=back
95c6c5c5 151
e96e0834 152=head1 Diagnostics
95c6c5c5 153
e96e0834
JL
154The following additions or changes have been made to diagnostic output,
155including warnings and fatal error messages. For the complete list of
156diagnostic messages, see L<perldiag>.
95c6c5c5 157
e96e0834
JL
158XXX New or changed warnings emitted by the core's C<C> code go here. Also
159include any changes in L<perldiag> that reconcile it to the C<C> code.
71014848 160
e96e0834
JL
161[ Within each section, list entries as a =item entry that links to perldiag,
162 e.g.
71014848 163
e96e0834 164 =item *
95c6c5c5 165
e96e0834
JL
166 L<Invalid version object|perldiag/"Invalid version object">
167]
95c6c5c5 168
e96e0834 169=head2 New Diagnostics
95c6c5c5 170
e96e0834 171XXX Newly added diagnostic messages go here
95c6c5c5 172
e96e0834 173=head3 New Errors
95c6c5c5 174
e96e0834 175=over 4
95c6c5c5 176
95c6c5c5
JL
177=item *
178
e96e0834 179XXX L<message|perldiag/"message">
95c6c5c5 180
e96e0834 181=back
95c6c5c5 182
e96e0834 183=head3 New Warnings
95c6c5c5 184
e96e0834 185=over 4
95c6c5c5 186
95c6c5c5
JL
187=item *
188
e96e0834 189XXX L<message|perldiag/"message">
7d101ed1 190
e96e0834 191=back
d9661073 192
e96e0834 193=head2 Changes to Existing Diagnostics
95c6c5c5 194
e96e0834 195XXX Changes (i.e. rewording) of diagnostic messages go here
95c6c5c5 196
e96e0834 197=over 4
95c6c5c5
JL
198
199=item *
200
e96e0834 201XXX Describe change here
3630f57e 202
e96e0834 203=back
3630f57e 204
e96e0834 205=head1 Utility Changes
95c6c5c5 206
e96e0834
JL
207XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
208here. Most of these are built within the directories F<utils> and F<x2p>.
95c6c5c5 209
e96e0834
JL
210[ List utility changes as a =head3 entry for each utility and =item
211entries for each change
212Use L<XXX> with program names to get proper documentation linking. ]
95c6c5c5 213
e96e0834 214=head3 L<XXX>
95c6c5c5 215
e96e0834 216=over 4
95c6c5c5
JL
217
218=item *
219
e96e0834 220XXX
95c6c5c5 221
e96e0834 222=back
95c6c5c5 223
e96e0834 224=head1 Configuration and Compilation
95c6c5c5 225
e96e0834
JL
226XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
227go here. Any other changes to the Perl build process should be listed here.
228However, any platform-specific changes should be listed in the
229L</Platform Support> section, instead.
95c6c5c5 230
e96e0834 231[ List changes as a =item entry ].
95c6c5c5 232
e96e0834 233=over 4
95c6c5c5
JL
234
235=item *
236
e96e0834 237XXX
95c6c5c5 238
e96e0834 239=back
95c6c5c5 240
e96e0834 241=head1 Testing
95c6c5c5 242
e96e0834
JL
243XXX Any significant changes to the testing of a freshly built perl should be
244listed here. Changes which create B<new> files in F<t/> go here as do any
245large changes to the testing harness (e.g. when parallel testing was added).
246Changes to existing files in F<t/> aren't worth summarising, although the bugs
247that they represent may be covered elsewhere.
95c6c5c5 248
e96e0834 249[ List each test improvement as a =item entry ]
95c6c5c5 250
e96e0834 251=over 4
95c6c5c5
JL
252
253=item *
254
e96e0834 255XXX
95c6c5c5 256
61174fb5 257=back
f558db2f 258
e96e0834 259=head1 Platform Support
05c8f9ed 260
e96e0834 261XXX Any changes to platform support should be listed in the sections below.
05c8f9ed 262
e96e0834
JL
263[ Within the sections, list each platform as a =item entry with specific
264changes as paragraphs below it. ]
9dea6244 265
e96e0834 266=head2 New Platforms
9dea6244 267
e96e0834
JL
268XXX List any platforms that this version of perl compiles on, that previous
269versions did not. These will either be enabled by new files in the F<hints/>
270directories, or new subdirectories and F<README> files at the top level of the
271source tree.
7d101ed1
JL
272
273=over 4
274
e96e0834 275=item XXX-some-platform
7d101ed1 276
e96e0834 277XXX
7d101ed1
JL
278
279=back
280
e96e0834 281=head2 Discontinued Platforms
ef7131e9 282
e96e0834 283XXX List any platforms that this version of perl no longer compiles on.
4a301309
FC
284
285=over 4
286
e96e0834 287=item XXX-some-platform
8dffc0ab 288
e96e0834 289XXX
dbc84d79 290
4a301309
FC
291=back
292
61174fb5 293=head2 Platform-Specific Notes
ceb0881c 294
e96e0834
JL
295XXX List any changes for specific platforms. This could include configuration
296and compilation changes or changes in portability/compatibility. However,
297changes within modules for platforms should generally be listed in the
298L</Modules and Pragmata> section.
89cbc6b8 299
e96e0834 300=over 4
0998713f 301
e96e0834 302=item XXX-some-platform
112b6866 303
e96e0834 304XXX
112b6866 305
61174fb5 306=back
8e125188 307
61174fb5 308=head1 Internal Changes
8e125188 309
e96e0834
JL
310XXX Changes which affect the interface available to C<XS> code go here.
311Other significant internal changes for future core maintainers should
312be noted as well.
c4643160 313
e96e0834 314[ List each change as a =item entry ]
f8ef51fd 315
e96e0834 316=over 4
e128ab2c 317
e2f0c3bb
FC
318=item *
319
e96e0834 320XXX
e2f0c3bb 321
61174fb5 322=back
422287bf 323
61174fb5 324=head1 Selected Bug Fixes
2de6ba8d 325
e96e0834
JL
326XXX Important bug fixes in the core language are summarised here.
327Bug fixes in files in F<ext/> and F<lib/> are best summarised in
328L</Modules and Pragmata>.
52c4b146 329
e96e0834 330[ List each fix as a =item entry ]
e128ab2c
DM
331
332=over 4
333
334=item *
335
48895a0d
KW
336A regression introduced in v5.14.0 has been fixed, in which some calls
337to the C<re> module would clobber C<$_>.
e128ab2c 338
8b1adbab
JL
339=item *
340
341C<do FILE> now always either sets or clears C<$@>, even when the file can't be
342read. This ensures that testing C<$@> first (as recommended by the
343documentation) always returns the correct result.
344
83f29afa
VP
345=item *
346
347The array iterator used for the C<each @array> construct is now correctly
348reset when C<@array> is cleared (RT #75596). This happens for example when the
349array is globally assigned to, as in C<@array = (...)>, but not when its
350B<values> are assigned to. In terms of the XS API, it means that C<av_clear()>
351will now reset the iterator.
352
353This mirrors the behaviour of the hash iterator when the hash is cleared.
354
0938f143
JL
355=item *
356
357C<< $class->can >>, C<< $class->isa >>, and C<< $class->DOES >> now return
358correct results, regardless of whether that package referred to by C<$class>
359exists [perl #47113].
360
e128ab2c
DM
361=back
362
e96e0834 363=head1 Known Problems
dbc84d79 364
e96e0834
JL
365XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
366tests that had to be C<TODO>ed for the release would be noted here. Unfixed
367platform specific bugs also go here.
53de3ff0 368
e96e0834 369[ List each fix as a =item entry ]
233bba44
JL
370
371=over 4
372
373=item *
374
e96e0834 375XXX
233bba44 376
e96e0834 377=back
233bba44 378
e96e0834 379=head1 Obituary
233bba44 380
e96e0834
JL
381XXX If any significant core contributor has died, we've added a short obituary
382here.
233bba44 383
61174fb5 384=head1 Acknowledgements
d5dc7001 385
e96e0834
JL
386XXX Generate this with:
387
388 perl Porting/acknowledgements.pl v5.17.1..HEAD
29cf780c 389
44691e6f
AB
390=head1 Reporting Bugs
391
392If you find what you think is a bug, you might check the articles
52deee2e 393recently posted to the comp.lang.perl.misc newsgroup and the perl
f9001595
RS
394bug database at http://rt.perl.org/perlbug/ . There may also be
395information at http://www.perl.org/ , the Perl Home Page.
44691e6f
AB
396
397If you believe you have an unreported bug, please run the L<perlbug>
52deee2e
DR
398program included with your release. Be sure to trim your bug down
399to a tiny but sufficient test case. Your bug report, along with the
400output of C<perl -V>, will be sent off to perlbug@perl.org to be
401analysed by the Perl porting team.
44691e6f
AB
402
403If the bug you are reporting has security implications, which make it
f9001595
RS
404inappropriate to send to a publicly archived mailing list, then please send
405it to perl5-security-report@perl.org. This points to a closed subscription
406unarchived mailing list, which includes
407all the core committers, who will be able
408to help assess the impact of issues, figure out a resolution, and help
409co-ordinate the release of patches to mitigate or fix the problem across all
410platforms on which Perl is supported. Please only use this address for
411security issues in the Perl core, not for modules independently
412distributed on CPAN.
44691e6f
AB
413
414=head1 SEE ALSO
415
52deee2e
DR
416The F<Changes> file for an explanation of how to view exhaustive details
417on what changed.
44691e6f
AB
418
419The F<INSTALL> file for how to build Perl.
420
421The F<README> file for general stuff.
422
423The F<Artistic> and F<Copying> files for copyright information.
424
425=cut