This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
sv.h: Document SvTHINKFIRST
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
4eabcf70
TC
5[ this is a template for a new perldelta file. Any text flagged as
6XXX needs to be processed before release. ]
417a992d 7
4eabcf70 8perldelta - what is new for perl v5.17.3
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
4eabcf70
TC
12This document describes differences between the 5.17.2 release and
13the 5.17.3 release.
6db9054f 14
4eabcf70
TC
15If you are upgrading from an earlier release such as 5.17.1, first read
16L<perl5172delta>, which describes differences between 5.17.1 and
175.17.2.
ef7131e9 18
4eabcf70 19=head1 Notice
ff3f295c 20
4eabcf70 21XXX Any important notices here
95c6c5c5 22
4eabcf70 23=head1 Core Enhancements
95c6c5c5 24
4eabcf70
TC
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.
4c77591b 28
4eabcf70 29[ List each enhancement as a =head2 entry ]
c506fc7e 30
6ed07037
FC
31=head2 Computed Labels
32
33The loop controls C<next>, C<last> and C<redo>, and the special C<dump>
34operator, now allow arbitrary expressions to be used to compute labels at
35run time. Previously, any argument that was not a constant was treated as
36the empty string.
37
4eabcf70 38=head1 Security
36ab1671 39
4eabcf70
TC
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.
36ab1671 43
4eabcf70 44[ List each security issue as a =head2 entry ]
36ab1671 45
4eabcf70 46=head1 Incompatible Changes
df2c1bb8 47
613c63b4 48[ List each incompatible change as a =head2 entry ]
df2c1bb8 49
613c63b4 50=head2 C<$ENV{foo} = undef> deletes value from environ, like C<delete $ENV{foo}>
df2c1bb8 51
613c63b4
CS
52This facilitates use of C<local()> with C<%ENV> entries. In previous
53versions of Perl, C<undef> was converted to the empty string.
54
55=head2 Defined values stored in environment are forced to byte strings
56
57A value stored in an environment variable has always been stringified. In
58this release, it is converted to be only a byte string. First, it is forced
59to be a only a string. Then if the string is utf8 and the equivalent of
60C<utf8::downgrade> works, that result is used; otherwise, the equivalent of
61C<utf8::encode> is used, and a warning is issued about wide characters
62(L</Diagnostics>).
7ab2ea42 63
4eabcf70 64=head1 Deprecations
7ab2ea42 65
4eabcf70
TC
66XXX Any deprecated features, syntax, modules etc. should be listed here.
67In particular, deprecated modules should be listed here even if they are
68listed as an updated module in the L</Modules and Pragmata> section.
7ab2ea42 69
4eabcf70 70[ List each deprecation as a =head2 entry ]
7ab2ea42 71
4eabcf70 72=head1 Performance Enhancements
3be135d8 73
4eabcf70
TC
74XXX Changes which enhance performance without changing behaviour go here. There
75may well be none in a stable release.
3be135d8 76
4eabcf70 77[ List each enhancement as a =item entry ]
6db9054f 78
4eabcf70 79=over 4
6db9054f 80
7ca04d94
TC
81=item *
82
4eabcf70 83XXX
7ca04d94 84
e96e0834 85=back
c506fc7e 86
4eabcf70 87=head1 Modules and Pragmata
95c6c5c5 88
4eabcf70
TC
89XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
90go here. If Module::CoreList is updated, generate an initial draft of the
91following sections using F<Porting/corelist-perldelta.pl>, which prints stub
92entries to STDOUT. Results can be pasted in place of the '=head2' entries
93below. A paragraph summary for important changes should then be added by hand.
94In an ideal world, dual-life modules would have a F<Changes> file that could be
95cribbed.
95c6c5c5 96
4eabcf70
TC
97[ Within each section, list entries as a =item entry ]
98
99=head2 New Modules and Pragmata
95c6c5c5 100
e96e0834 101=over 4
95c6c5c5
JL
102
103=item *
104
4eabcf70 105XXX
95c6c5c5 106
e96e0834 107=back
95c6c5c5 108
4eabcf70 109=head2 Updated Modules and Pragmata
95c6c5c5 110
e96e0834 111=over 4
95c6c5c5 112
95c6c5c5
JL
113=item *
114
6b1793dd
NC
115L<B> has been upgraded from version 1.36 to version 1.37. All C<CVf_*> and
116C<GVf_*> and more SV-related flag values are now provided as constants in
117the C<B::> namespace and available for export. The default export list has
118not changed.
b8a55fe7 119
32ed16fc
FC
120=item *
121
122L<B::Deparse> has been upgraded from version 1.15 to 1.16. It now deparses
123loop controls with the correct precedence.
124
e96e0834 125=back
95c6c5c5 126
4eabcf70 127=head2 Removed Modules and Pragmata
95c6c5c5 128
e96e0834 129=over 4
95c6c5c5 130
95c6c5c5
JL
131=item *
132
4eabcf70 133XXX
4f85bc45 134
4eabcf70 135=back
72267260 136
4eabcf70 137=head1 Documentation
72267260 138
4eabcf70
TC
139XXX Changes to files in F<pod/> go here. Consider grouping entries by
140file and be sure to link to the appropriate page, e.g. L<perlfunc>.
4f85bc45 141
4eabcf70 142=head2 New Documentation
7d101ed1 143
4eabcf70 144XXX Changes which create B<new> files in F<pod/> go here.
e013ada0 145
4eabcf70 146=head3 L<XXX>
4f85bc45 147
4eabcf70 148XXX Description of the purpose of the new file here
e013ada0 149
4eabcf70 150=head2 Changes to Existing Documentation
95c6c5c5 151
4eabcf70
TC
152XXX Changes which significantly change existing files in F<pod/> go here.
153However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
154section.
95c6c5c5 155
be28af6e 156=head3 L<perlfunc>, L<perlop>
95c6c5c5 157
e96e0834 158=over 4
95c6c5c5
JL
159
160=item *
161
be28af6e
FC
162Loop control verbs (C<dump>, C<goto>, C<next>, C<last> and C<redo>) have
163always had the same precedence as assignment operators, but this was never
164documented until now.
95c6c5c5 165
e96e0834 166=back
95c6c5c5 167
4eabcf70 168=head1 Diagnostics
05c8f9ed 169
4eabcf70
TC
170The following additions or changes have been made to diagnostic output,
171including warnings and fatal error messages. For the complete list of
172diagnostic messages, see L<perldiag>.
ceb0881c 173
4eabcf70
TC
174XXX New or changed warnings emitted by the core's C<C> code go here. Also
175include any changes in L<perldiag> that reconcile it to the C<C> code.
0998713f 176
4eabcf70
TC
177[ Within each section, list entries as a =item entry that links to perldiag,
178 e.g.
112b6866 179
4eabcf70 180 =item *
112b6866 181
4eabcf70
TC
182 L<Invalid version object|perldiag/"Invalid version object">
183]
42d72fc5 184
4eabcf70 185=head2 New Diagnostics
42d72fc5 186
4eabcf70 187XXX Newly added diagnostic messages go here
8e125188 188
613c63b4
CS
189=over 4
190
191=item *
192
193Attempts to put wide characters into environment variables via %ENV provoke
194the warning "Wide character in setenv".
195
196=back
197
4eabcf70 198=head3 New Errors
8e125188 199
e96e0834 200=over 4
e128ab2c 201
e2f0c3bb
FC
202=item *
203
4eabcf70 204XXX L<message|perldiag/"message">
16e4fcbf 205
4eabcf70 206=back
e2f0c3bb 207
4eabcf70 208=head3 New Warnings
90519d0f 209
4eabcf70 210=over 4
90519d0f
FC
211
212=item *
213
4eabcf70 214XXX L<message|perldiag/"message">
90519d0f 215
61174fb5 216=back
422287bf 217
4eabcf70
TC
218=head2 Changes to Existing Diagnostics
219
220XXX Changes (i.e. rewording) of diagnostic messages go here
2de6ba8d 221
e128ab2c
DM
222=over 4
223
224=item *
225
4eabcf70 226XXX Describe change here
e128ab2c 227
4eabcf70 228=back
8b1adbab 229
4eabcf70 230=head1 Utility Changes
8b1adbab 231
4eabcf70
TC
232XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
233here. Most of these are built within the directories F<utils> and F<x2p>.
83f29afa 234
4eabcf70
TC
235[ List utility changes as a =head3 entry for each utility and =item
236entries for each change
237Use L<XXX> with program names to get proper documentation linking. ]
83f29afa 238
4eabcf70 239=head3 L<XXX>
0938f143 240
4eabcf70 241=over 4
0938f143 242
72267260
JL
243=item *
244
4eabcf70 245XXX
7a251f7a 246
4eabcf70 247=back
7a251f7a 248
4eabcf70 249=head1 Configuration and Compilation
21247d85 250
4eabcf70
TC
251XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
252go here. Any other changes to the Perl build process should be listed here.
253However, any platform-specific changes should be listed in the
254L</Platform Support> section, instead.
21247d85 255
4eabcf70 256[ List changes as a =item entry ].
2e4f8b82 257
4eabcf70 258=over 4
c95d4104 259
788505db
FC
260=item *
261
4eabcf70 262XXX
788505db 263
4eabcf70 264=back
2c2b9cf4 265
4eabcf70 266=head1 Testing
3cd56aaa 267
4eabcf70
TC
268XXX Any significant changes to the testing of a freshly built perl should be
269listed here. Changes which create B<new> files in F<t/> go here as do any
270large changes to the testing harness (e.g. when parallel testing was added).
271Changes to existing files in F<t/> aren't worth summarising, although the bugs
272that they represent may be covered elsewhere.
3cd56aaa 273
4eabcf70 274[ List each test improvement as a =item entry ]
3cd56aaa 275
4eabcf70 276=over 4
3cd56aaa
TC
277
278=item *
279
4eabcf70 280XXX
3cd56aaa 281
4eabcf70 282=back
3cd56aaa 283
4eabcf70 284=head1 Platform Support
3cd56aaa 285
4eabcf70 286XXX Any changes to platform support should be listed in the sections below.
3cd56aaa 287
4eabcf70
TC
288[ Within the sections, list each platform as a =item entry with specific
289changes as paragraphs below it. ]
3cd56aaa 290
4eabcf70 291=head2 New Platforms
3cd56aaa 292
4eabcf70
TC
293XXX List any platforms that this version of perl compiles on, that previous
294versions did not. These will either be enabled by new files in the F<hints/>
295directories, or new subdirectories and F<README> files at the top level of the
296source tree.
3cd56aaa 297
4eabcf70 298=over 4
3cd56aaa 299
4eabcf70 300=item XXX-some-platform
3cd56aaa 301
4eabcf70 302XXX
c0c19433 303
4eabcf70 304=back
c0c19433 305
4eabcf70 306=head2 Discontinued Platforms
7ab2ea42 307
4eabcf70 308XXX List any platforms that this version of perl no longer compiles on.
7ab2ea42 309
4eabcf70 310=over 4
7ab2ea42 311
4eabcf70 312=item XXX-some-platform
7ab2ea42 313
4eabcf70 314XXX
90519d0f 315
4eabcf70 316=back
90519d0f 317
4eabcf70 318=head2 Platform-Specific Notes
90519d0f 319
4eabcf70
TC
320XXX List any changes for specific platforms. This could include configuration
321and compilation changes or changes in portability/compatibility. However,
322changes within modules for platforms should generally be listed in the
323L</Modules and Pragmata> section.
90519d0f 324
4eabcf70 325=over 4
90519d0f 326
4eabcf70 327=item XXX-some-platform
90519d0f 328
4eabcf70 329XXX
90519d0f 330
4eabcf70 331=back
90519d0f 332
4eabcf70 333=head1 Internal Changes
90519d0f 334
4eabcf70
TC
335XXX Changes which affect the interface available to C<XS> code go here.
336Other significant internal changes for future core maintainers should
337be noted as well.
90519d0f 338
4eabcf70 339[ List each change as a =item entry ]
90519d0f 340
4eabcf70 341=over 4
90519d0f
FC
342
343=item *
344
4eabcf70 345XXX
90519d0f 346
4eabcf70 347=back
90519d0f 348
4eabcf70 349=head1 Selected Bug Fixes
90519d0f 350
4eabcf70
TC
351XXX Important bug fixes in the core language are summarised here.
352Bug fixes in files in F<ext/> and F<lib/> are best summarised in
353L</Modules and Pragmata>.
90519d0f 354
4eabcf70 355[ List each fix as a =item entry ]
90519d0f 356
4eabcf70 357=over 4
90519d0f
FC
358
359=item *
360
7a4d6ad6
KW
361C<\w> now matches the code points U+200C (ZERO WIDTH NON-JOINER) and
362U+200D (ZERO WIDTH JOINER). C<\W> no longer matches these. This change
363is because Unicode corrected their definition of what C<\w> should match.
90519d0f 364
77f5d539
FC
365=item *
366
367C<dump LABEL> no longer leaks its label.
368
3e81bef2
FC
369=item *
370
371Constant folding no longer changes the behaviour of functions like C<stat>
372and C<truncate> that can take either filenames or handles.
373C<stat 1 ? foo : bar> nows treats its argument as a file name (since it is
374an arbitrary expression), rather than the handle "foo".
375
e9f497c4
FC
376=item *
377
378C<truncate FOO, $len> no longer falls back to treating "FOO" as a file name
379if the filehandle has been deleted. This was broken in Perl 5.16.0.
380
d7f7c515
FC
381=item *
382
383Subroutine redefinitions after sub-to-glob and glob-to-glob assignments no
384longer cause double frees or panic messages.
385
4eabcf70 386=back
90519d0f 387
4eabcf70 388=head1 Known Problems
b8a55fe7 389
4eabcf70
TC
390XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
391tests that had to be C<TODO>ed for the release would be noted here. Unfixed
392platform specific bugs also go here.
b8a55fe7 393
4eabcf70 394[ List each fix as a =item entry ]
b8a55fe7 395
4eabcf70 396=over 4
b8a55fe7
FC
397
398=item *
399
4eabcf70 400XXX
b8a55fe7 401
4eabcf70 402=back
5073ffbd 403
4eabcf70 404=head1 Obituary
5073ffbd 405
4eabcf70
TC
406XXX If any significant core contributor has died, we've added a short obituary
407here.
e128ab2c 408
61174fb5 409=head1 Acknowledgements
d5dc7001 410
4eabcf70
TC
411XXX Generate this with:
412
413 perl Porting/acknowledgements.pl v5.17.2..HEAD
29cf780c 414
44691e6f
AB
415=head1 Reporting Bugs
416
417If you find what you think is a bug, you might check the articles
52deee2e 418recently posted to the comp.lang.perl.misc newsgroup and the perl
f9001595
RS
419bug database at http://rt.perl.org/perlbug/ . There may also be
420information at http://www.perl.org/ , the Perl Home Page.
44691e6f
AB
421
422If you believe you have an unreported bug, please run the L<perlbug>
52deee2e
DR
423program included with your release. Be sure to trim your bug down
424to a tiny but sufficient test case. Your bug report, along with the
425output of C<perl -V>, will be sent off to perlbug@perl.org to be
426analysed by the Perl porting team.
44691e6f
AB
427
428If the bug you are reporting has security implications, which make it
f9001595
RS
429inappropriate to send to a publicly archived mailing list, then please send
430it to perl5-security-report@perl.org. This points to a closed subscription
431unarchived mailing list, which includes
432all the core committers, who will be able
433to help assess the impact of issues, figure out a resolution, and help
434co-ordinate the release of patches to mitigate or fix the problem across all
435platforms on which Perl is supported. Please only use this address for
436security issues in the Perl core, not for modules independently
437distributed on CPAN.
44691e6f
AB
438
439=head1 SEE ALSO
440
52deee2e
DR
441The F<Changes> file for an explanation of how to view exhaustive details
442on what changed.
44691e6f
AB
443
444The F<INSTALL> file for how to build Perl.
445
446The F<README> file for general stuff.
447
448The F<Artistic> and F<Copying> files for copyright information.
449
450=cut