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