This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Make all the SvPV*force* macros always return sv with SvPOK_only, as API
[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
4eabcf70 31=head1 Security
36ab1671 32
4eabcf70
TC
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.
36ab1671 36
4eabcf70 37[ List each security issue as a =head2 entry ]
36ab1671 38
4eabcf70 39=head1 Incompatible Changes
df2c1bb8 40
4eabcf70 41XXX For a release on a stable branch, this section aspires to be:
df2c1bb8 42
4eabcf70
TC
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.
df2c1bb8 46
4eabcf70 47[ List each incompatible change as a =head2 entry ]
7ab2ea42 48
4eabcf70 49=head1 Deprecations
7ab2ea42 50
4eabcf70
TC
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.
7ab2ea42 54
4eabcf70 55[ List each deprecation as a =head2 entry ]
7ab2ea42 56
4eabcf70 57=head1 Performance Enhancements
3be135d8 58
4eabcf70
TC
59XXX Changes which enhance performance without changing behaviour go here. There
60may well be none in a stable release.
3be135d8 61
4eabcf70 62[ List each enhancement as a =item entry ]
6db9054f 63
4eabcf70 64=over 4
6db9054f 65
7ca04d94
TC
66=item *
67
4eabcf70 68XXX
7ca04d94 69
e96e0834 70=back
c506fc7e 71
4eabcf70 72=head1 Modules and Pragmata
95c6c5c5 73
4eabcf70
TC
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.
95c6c5c5 81
4eabcf70
TC
82[ Within each section, list entries as a =item entry ]
83
84=head2 New Modules and Pragmata
95c6c5c5 85
e96e0834 86=over 4
95c6c5c5
JL
87
88=item *
89
4eabcf70 90XXX
95c6c5c5 91
e96e0834 92=back
95c6c5c5 93
4eabcf70 94=head2 Updated Modules and Pragmata
95c6c5c5 95
e96e0834 96=over 4
95c6c5c5 97
95c6c5c5
JL
98=item *
99
6b1793dd
NC
100L<B> has been upgraded from version 1.36 to version 1.37. All C<CVf_*> and
101C<GVf_*> and more SV-related flag values are now provided as constants in
102the C<B::> namespace and available for export. The default export list has
103not changed.
b8a55fe7 104
e96e0834 105=back
95c6c5c5 106
4eabcf70 107=head2 Removed Modules and Pragmata
95c6c5c5 108
e96e0834 109=over 4
95c6c5c5 110
95c6c5c5
JL
111=item *
112
4eabcf70 113XXX
4f85bc45 114
4eabcf70 115=back
72267260 116
4eabcf70 117=head1 Documentation
72267260 118
4eabcf70
TC
119XXX Changes to files in F<pod/> go here. Consider grouping entries by
120file and be sure to link to the appropriate page, e.g. L<perlfunc>.
4f85bc45 121
4eabcf70 122=head2 New Documentation
7d101ed1 123
4eabcf70 124XXX Changes which create B<new> files in F<pod/> go here.
e013ada0 125
4eabcf70 126=head3 L<XXX>
4f85bc45 127
4eabcf70 128XXX Description of the purpose of the new file here
e013ada0 129
4eabcf70 130=head2 Changes to Existing Documentation
95c6c5c5 131
4eabcf70
TC
132XXX Changes which significantly change existing files in F<pod/> go here.
133However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
134section.
95c6c5c5 135
4eabcf70 136=head3 L<XXX>
95c6c5c5 137
e96e0834 138=over 4
95c6c5c5
JL
139
140=item *
141
4eabcf70 142XXX Description of the change here
95c6c5c5 143
e96e0834 144=back
95c6c5c5 145
4eabcf70 146=head1 Diagnostics
05c8f9ed 147
4eabcf70
TC
148The following additions or changes have been made to diagnostic output,
149including warnings and fatal error messages. For the complete list of
150diagnostic messages, see L<perldiag>.
ceb0881c 151
4eabcf70
TC
152XXX New or changed warnings emitted by the core's C<C> code go here. Also
153include any changes in L<perldiag> that reconcile it to the C<C> code.
0998713f 154
4eabcf70
TC
155[ Within each section, list entries as a =item entry that links to perldiag,
156 e.g.
112b6866 157
4eabcf70 158 =item *
112b6866 159
4eabcf70
TC
160 L<Invalid version object|perldiag/"Invalid version object">
161]
42d72fc5 162
4eabcf70 163=head2 New Diagnostics
42d72fc5 164
4eabcf70 165XXX Newly added diagnostic messages go here
8e125188 166
4eabcf70 167=head3 New Errors
8e125188 168
e96e0834 169=over 4
e128ab2c 170
e2f0c3bb
FC
171=item *
172
4eabcf70 173XXX L<message|perldiag/"message">
16e4fcbf 174
4eabcf70 175=back
e2f0c3bb 176
4eabcf70 177=head3 New Warnings
90519d0f 178
4eabcf70 179=over 4
90519d0f
FC
180
181=item *
182
4eabcf70 183XXX L<message|perldiag/"message">
90519d0f 184
61174fb5 185=back
422287bf 186
4eabcf70
TC
187=head2 Changes to Existing Diagnostics
188
189XXX Changes (i.e. rewording) of diagnostic messages go here
2de6ba8d 190
e128ab2c
DM
191=over 4
192
193=item *
194
4eabcf70 195XXX Describe change here
e128ab2c 196
4eabcf70 197=back
8b1adbab 198
4eabcf70 199=head1 Utility Changes
8b1adbab 200
4eabcf70
TC
201XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
202here. Most of these are built within the directories F<utils> and F<x2p>.
83f29afa 203
4eabcf70
TC
204[ List utility changes as a =head3 entry for each utility and =item
205entries for each change
206Use L<XXX> with program names to get proper documentation linking. ]
83f29afa 207
4eabcf70 208=head3 L<XXX>
0938f143 209
4eabcf70 210=over 4
0938f143 211
72267260
JL
212=item *
213
4eabcf70 214XXX
7a251f7a 215
4eabcf70 216=back
7a251f7a 217
4eabcf70 218=head1 Configuration and Compilation
21247d85 219
4eabcf70
TC
220XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
221go here. Any other changes to the Perl build process should be listed here.
222However, any platform-specific changes should be listed in the
223L</Platform Support> section, instead.
21247d85 224
4eabcf70 225[ List changes as a =item entry ].
2e4f8b82 226
4eabcf70 227=over 4
c95d4104 228
788505db
FC
229=item *
230
4eabcf70 231XXX
788505db 232
4eabcf70 233=back
2c2b9cf4 234
4eabcf70 235=head1 Testing
3cd56aaa 236
4eabcf70
TC
237XXX Any significant changes to the testing of a freshly built perl should be
238listed here. Changes which create B<new> files in F<t/> go here as do any
239large changes to the testing harness (e.g. when parallel testing was added).
240Changes to existing files in F<t/> aren't worth summarising, although the bugs
241that they represent may be covered elsewhere.
3cd56aaa 242
4eabcf70 243[ List each test improvement as a =item entry ]
3cd56aaa 244
4eabcf70 245=over 4
3cd56aaa
TC
246
247=item *
248
4eabcf70 249XXX
3cd56aaa 250
4eabcf70 251=back
3cd56aaa 252
4eabcf70 253=head1 Platform Support
3cd56aaa 254
4eabcf70 255XXX Any changes to platform support should be listed in the sections below.
3cd56aaa 256
4eabcf70
TC
257[ Within the sections, list each platform as a =item entry with specific
258changes as paragraphs below it. ]
3cd56aaa 259
4eabcf70 260=head2 New Platforms
3cd56aaa 261
4eabcf70
TC
262XXX List any platforms that this version of perl compiles on, that previous
263versions did not. These will either be enabled by new files in the F<hints/>
264directories, or new subdirectories and F<README> files at the top level of the
265source tree.
3cd56aaa 266
4eabcf70 267=over 4
3cd56aaa 268
4eabcf70 269=item XXX-some-platform
3cd56aaa 270
4eabcf70 271XXX
c0c19433 272
4eabcf70 273=back
c0c19433 274
4eabcf70 275=head2 Discontinued Platforms
7ab2ea42 276
4eabcf70 277XXX List any platforms that this version of perl no longer compiles on.
7ab2ea42 278
4eabcf70 279=over 4
7ab2ea42 280
4eabcf70 281=item XXX-some-platform
7ab2ea42 282
4eabcf70 283XXX
90519d0f 284
4eabcf70 285=back
90519d0f 286
4eabcf70 287=head2 Platform-Specific Notes
90519d0f 288
4eabcf70
TC
289XXX List any changes for specific platforms. This could include configuration
290and compilation changes or changes in portability/compatibility. However,
291changes within modules for platforms should generally be listed in the
292L</Modules and Pragmata> section.
90519d0f 293
4eabcf70 294=over 4
90519d0f 295
4eabcf70 296=item XXX-some-platform
90519d0f 297
4eabcf70 298XXX
90519d0f 299
4eabcf70 300=back
90519d0f 301
4eabcf70 302=head1 Internal Changes
90519d0f 303
4eabcf70
TC
304XXX Changes which affect the interface available to C<XS> code go here.
305Other significant internal changes for future core maintainers should
306be noted as well.
90519d0f 307
4eabcf70 308[ List each change as a =item entry ]
90519d0f 309
4eabcf70 310=over 4
90519d0f
FC
311
312=item *
313
4eabcf70 314XXX
90519d0f 315
4eabcf70 316=back
90519d0f 317
4eabcf70 318=head1 Selected Bug Fixes
90519d0f 319
4eabcf70
TC
320XXX Important bug fixes in the core language are summarised here.
321Bug fixes in files in F<ext/> and F<lib/> are best summarised in
322L</Modules and Pragmata>.
90519d0f 323
4eabcf70 324[ List each fix as a =item entry ]
90519d0f 325
4eabcf70 326=over 4
90519d0f
FC
327
328=item *
329
7a4d6ad6
KW
330C<\w> now matches the code points U+200C (ZERO WIDTH NON-JOINER) and
331U+200D (ZERO WIDTH JOINER). C<\W> no longer matches these. This change
332is because Unicode corrected their definition of what C<\w> should match.
90519d0f 333
4eabcf70 334=back
90519d0f 335
4eabcf70 336=head1 Known Problems
b8a55fe7 337
4eabcf70
TC
338XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
339tests that had to be C<TODO>ed for the release would be noted here. Unfixed
340platform specific bugs also go here.
b8a55fe7 341
4eabcf70 342[ List each fix as a =item entry ]
b8a55fe7 343
4eabcf70 344=over 4
b8a55fe7
FC
345
346=item *
347
4eabcf70 348XXX
b8a55fe7 349
4eabcf70 350=back
5073ffbd 351
4eabcf70 352=head1 Obituary
5073ffbd 353
4eabcf70
TC
354XXX If any significant core contributor has died, we've added a short obituary
355here.
e128ab2c 356
61174fb5 357=head1 Acknowledgements
d5dc7001 358
4eabcf70
TC
359XXX Generate this with:
360
361 perl Porting/acknowledgements.pl v5.17.2..HEAD
29cf780c 362
44691e6f
AB
363=head1 Reporting Bugs
364
365If you find what you think is a bug, you might check the articles
52deee2e 366recently posted to the comp.lang.perl.misc newsgroup and the perl
f9001595
RS
367bug database at http://rt.perl.org/perlbug/ . There may also be
368information at http://www.perl.org/ , the Perl Home Page.
44691e6f
AB
369
370If you believe you have an unreported bug, please run the L<perlbug>
52deee2e
DR
371program included with your release. Be sure to trim your bug down
372to a tiny but sufficient test case. Your bug report, along with the
373output of C<perl -V>, will be sent off to perlbug@perl.org to be
374analysed by the Perl porting team.
44691e6f
AB
375
376If the bug you are reporting has security implications, which make it
f9001595
RS
377inappropriate to send to a publicly archived mailing list, then please send
378it to perl5-security-report@perl.org. This points to a closed subscription
379unarchived mailing list, which includes
380all the core committers, who will be able
381to help assess the impact of issues, figure out a resolution, and help
382co-ordinate the release of patches to mitigate or fix the problem across all
383platforms on which Perl is supported. Please only use this address for
384security issues in the Perl core, not for modules independently
385distributed on CPAN.
44691e6f
AB
386
387=head1 SEE ALSO
388
52deee2e
DR
389The F<Changes> file for an explanation of how to view exhaustive details
390on what changed.
44691e6f
AB
391
392The F<INSTALL> file for how to build Perl.
393
394The F<README> file for general stuff.
395
396The F<Artistic> and F<Copying> files for copyright information.
397
398=cut