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