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