This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Porting/bump-perl-version: No need to try other maps after one has worked
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
a9c3e753
S
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.21.10
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
a9c3e753 12This document describes differences between the 5.21.9 release and the 5.21.10
238894db 13release.
c68523cb 14
a9c3e753
S
15If you are upgrading from an earlier release such as 5.21.8, first read
16L<perl5219delta>, which describes differences between 5.21.8 and 5.21.9.
2ec11c70 17
b5d4d3b9 18=head1 Notice
2ec11c70 19
a9c3e753 20XXX Any important notices here
67f2cc75 21
b5d4d3b9 22=head1 Core Enhancements
67f2cc75 23
a9c3e753
S
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.
06ae2722 27
a9c3e753 28[ List each enhancement as a =head2 entry ]
156f41cf 29
a9c3e753 30=head1 Security
156f41cf 31
a9c3e753
S
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.
156f41cf 35
a9c3e753 36[ List each security issue as a =head2 entry ]
48c4d243 37
b5d4d3b9 38=head1 Incompatible Changes
ef8784b7 39
a9c3e753 40XXX For a release on a stable branch, this section aspires to be:
541e1e0d 41
a9c3e753
S
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.
541e1e0d 45
a9c3e753 46[ List each incompatible change as a =head2 entry ]
541e1e0d 47
a9c3e753 48=head1 Deprecations
541e1e0d 49
a9c3e753 50XXX Any deprecated features, syntax, modules etc. should be listed here.
541e1e0d 51
a9c3e753 52=head2 Module removals
541e1e0d 53
a9c3e753 54XXX Remove this section if inapplicable.
541e1e0d 55
a9c3e753
S
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.
cd7bac54 60
a9c3e753
S
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.
541e1e0d 64
a9c3e753
S
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.
541e1e0d 69
a9c3e753 70=over
cd7bac54 71
a9c3e753 72=item XXX
6c8457e9 73
a9c3e753
S
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.
cd7bac54
S
76
77=back
6c8457e9 78
a9c3e753 79[ List each other deprecation as a =head2 entry ]
6c8457e9 80
a9c3e753 81=head1 Performance Enhancements
6c8457e9 82
a9c3e753
S
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
127a7155 85
a9c3e753 86[ List each enhancement as a =item entry ]
6c8457e9 87
cd7bac54
S
88=over 4
89
90=item *
91
a9c3e753 92XXX
cd7bac54
S
93
94=back
95
a9c3e753 96=head1 Modules and Pragmata
0939a951 97
a9c3e753
S
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.
c49582c3 103
a9c3e753 104[ Within each section, list entries as a =item entry ]
9024667a 105
a9c3e753 106=head2 New Modules and Pragmata
31e72f27
KW
107
108=over 4
109
110=item *
111
a9c3e753 112XXX
0ce5e53e 113
31e72f27
KW
114=back
115
a9c3e753 116=head2 Updated Modules and Pragmata
cd7bac54 117
a9c3e753 118=over 4
cd7bac54
S
119
120=item *
121
a9c3e753 122L<XXX> has been upgraded from version A.xx to B.yy.
0939a951 123
a9c3e753 124=back
0939a951 125
a9c3e753 126=head2 Removed Modules and Pragmata
cd7bac54 127
a9c3e753 128=over 4
cd7bac54
S
129
130=item *
131
a9c3e753 132XXX
cd7bac54 133
2ff1ebfe 134=back
541e1e0d 135
cd7bac54
S
136=head1 Documentation
137
a9c3e753
S
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>.
140
cd7bac54
S
141=head2 New Documentation
142
a9c3e753 143XXX Changes which create B<new> files in F<pod/> go here.
541e1e0d 144
a9c3e753 145=head3 L<XXX>
d676fe86 146
a9c3e753 147XXX Description of the purpose of the new file here
d676fe86 148
a9c3e753 149=head2 Changes to Existing Documentation
d2fff9f6 150
a9c3e753
S
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.
d2fff9f6 154
a9c3e753 155=head3 L<XXX>
e329daf3 156
cd7bac54 157=over 4
e329daf3 158
cd7bac54 159=item *
e329daf3 160
a9c3e753 161XXX Description of the change here
ba31029d 162
cd7bac54
S
163=back
164
a9c3e753 165=head1 Diagnostics
cd7bac54 166
a9c3e753
S
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>.
cd7bac54 170
a9c3e753
S
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.
cd7bac54 173
a9c3e753 174=head2 New Diagnostics
541e1e0d 175
a9c3e753
S
176XXX Newly added diagnostic messages go under here, separated into New Errors
177and New Warnings
541e1e0d 178
a9c3e753 179=head3 New Errors
cd7bac54
S
180
181=over 4
182
183=item *
184
a9c3e753 185XXX L<message|perldiag/"message">
cd7bac54
S
186
187=back
541e1e0d 188
a9c3e753 189=head3 New Warnings
541e1e0d 190
2ff1ebfe 191=over 4
aa67537d 192
4c7a0d98
DD
193=item *
194
a9c3e753 195XXX L<message|perldiag/"message">
4c7a0d98 196
b5d4d3b9 197=back
4c7a0d98 198
a9c3e753 199=head2 Changes to Existing Diagnostics
a5d66edf 200
a9c3e753 201XXX Changes (i.e. rewording) of diagnostic messages go here
f348c3d8 202
cd7bac54 203=over 4
f348c3d8 204
cd7bac54 205=item *
2ff1ebfe 206
a9c3e753 207XXX Describe change here
f348c3d8 208
cd7bac54 209=back
2ff1ebfe 210
a9c3e753 211=head1 Utility Changes
f348c3d8 212
a9c3e753
S
213XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
214Most of these are built within the directory F<utils>.
4dc623f0 215
a9c3e753
S
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. ]
84d03adf 219
a9c3e753 220=head2 L<XXX>
ff433f2d 221
9ce6583e 222=over 4
4cd408ba 223
9ce6583e 224=item *
6ed80d55 225
a9c3e753 226XXX
9ce6583e 227
2ff1ebfe 228=back
ab0b796c 229
a9c3e753 230=head1 Configuration and Compilation
cd7bac54 231
a9c3e753
S
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.
cd7bac54 236
a9c3e753 237[ List changes as a =item entry ].
8c6180a9 238
2ff1ebfe 239=over 4
0561e60b 240
9ce6583e 241=item *
dd200dff 242
a9c3e753 243XXX
c877af1b 244
cd7bac54 245=back
c877af1b 246
a9c3e753 247=head1 Testing
cd7bac54 248
a9c3e753
S
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.
cd7bac54 254
a9c3e753 255[ List each test improvement as a =item entry ]
bb8c7e27 256
b5d4d3b9 257=over 4
83b69bfd
DD
258
259=item *
260
a9c3e753 261XXX
13adb056 262
b5d4d3b9 263=back
391823f2 264
a9c3e753 265=head1 Platform Support
6c8457e9 266
a9c3e753 267XXX Any changes to platform support should be listed in the sections below.
6c8457e9 268
a9c3e753
S
269[ Within the sections, list each platform as a =item entry with specific
270changes as paragraphs below it. ]
db98db4e 271
a9c3e753 272=head2 New Platforms
8818afe8 273
a9c3e753
S
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.
8af808bf 278
2ff1ebfe 279=over 4
fdcaecb7 280
a9c3e753 281=item XXX-some-platform
fdcaecb7 282
a9c3e753 283XXX
2af7c6b6 284
4dc623f0 285=back
2af7c6b6 286
a9c3e753
S
287=head2 Discontinued Platforms
288
289XXX List any platforms that this version of perl no longer compiles on.
70cee83f 290
b5d4d3b9 291=over 4
e5fbfbc1 292
a9c3e753 293=item XXX-some-platform
b4045391 294
a9c3e753 295XXX
b4045391 296
2ff1ebfe 297=back
b4045391 298
2ff1ebfe 299=head2 Platform-Specific Notes
8c847e66 300
a9c3e753
S
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.
8c847e66 305
2ff1ebfe 306=over 4
d345f487 307
a9c3e753 308=item XXX-some-platform
d345f487 309
a9c3e753 310XXX
cd7bac54 311
4dc623f0 312=back
353075a0 313
a9c3e753 314=head1 Internal Changes
9f122eef 315
a9c3e753
S
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.
2ff1ebfe 319
a9c3e753 320[ List each change as a =item entry ]
2ff1ebfe 321
b5d4d3b9 322=over 4
2ec11c70
DM
323
324=item *
325
a9c3e753 326XXX
2683609f 327
4dc623f0 328=back
c7f058f0 329
4dc623f0 330=head1 Selected Bug Fixes
0ef4323a 331
a9c3e753
S
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>.
567291b6 334
a9c3e753 335[ List each fix as a =item entry ]
436f6503 336
a9c3e753 337=over 4
2bf83140 338
041a5927
FC
339=item *
340
a9c3e753 341XXX
041a5927 342
a9c3e753 343=back
ea13b07e 344
a9c3e753 345=head1 Known Problems
b65adbec 346
a9c3e753
S
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.
b65adbec 350
a9c3e753 351[ List each fix as a =item entry ]
370c71c5 352
a9c3e753 353=over 4
b94c7836
FC
354
355=item *
356
a9c3e753 357XXX
439f6100 358
a9c3e753 359=back
e3e8f263 360
a9c3e753 361=head1 Errata From Previous Releases
cd7bac54 362
a9c3e753 363=over 4
e3e8f263 364
cb6cc22b
TC
365=item *
366
a9c3e753
S
367XXX Add anything here that we forgot to add, or were mistaken about, in
368the perldelta of a previous release.
cb6cc22b 369
b5d4d3b9 370=back
fcfb7b86 371
a9c3e753 372=head1 Obituary
cd7bac54 373
a9c3e753
S
374XXX If any significant core contributor has died, we've added a short obituary
375here.
cd7bac54 376
a9c3e753 377=head1 Acknowledgements
541e1e0d 378
a9c3e753 379XXX Generate this with:
01d42a22 380
a9c3e753 381 perl Porting/acknowledgements.pl v5.21.9..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
238894db 387https://rt.perl.org/ . There may also be information at
7ef8b31d 388http://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