This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Replace common Emacs file-local variables with dir-locals
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
e5998677
SH
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.11
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
e5998677 12This document describes differences between the 5.21.10 release and the 5.21.11
238894db 13release.
c68523cb 14
e5998677
SH
15If you are upgrading from an earlier release such as 5.21.9, first read
16L<perl52110delta>, which describes differences between 5.21.9 and 5.21.10.
2ec11c70 17
e5998677 18=head1 Notice
ef8784b7 19
e5998677 20XXX Any important notices here
6798c95d 21
e5998677 22=head1 Core Enhancements
6798c95d 23
e5998677
SH
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.
cd7bac54 27
e5998677 28[ List each enhancement as a =head2 entry ]
cd7bac54 29
e5998677 30=head1 Security
0939a951 31
e5998677
SH
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.
cd7bac54 35
e5998677 36[ List each security issue as a =head2 entry ]
cd7bac54 37
e5998677 38=head1 Incompatible Changes
cd7bac54 39
e5998677 40XXX For a release on a stable branch, this section aspires to be:
83a5d6b6 41
e5998677
SH
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.
83a5d6b6 45
e5998677 46[ List each incompatible change as a =head2 entry ]
b9c683b3 47
e5998677 48=head1 Deprecations
b9c683b3 49
e5998677 50XXX Any deprecated features, syntax, modules etc. should be listed here.
b9c683b3 51
e5998677 52=head2 Module removals
b05565aa 53
e5998677 54XXX Remove this section if inapplicable.
b05565aa 55
e5998677
SH
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.
79116533 60
e5998677
SH
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.
79116533 64
e5998677
SH
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.
79116533 69
e5998677 70=over
79116533 71
e5998677 72=item XXX
79116533 73
e5998677
SH
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.
79116533 76
e5998677 77=back
79116533 78
e5998677 79[ List each other deprecation as a =head2 entry ]
79116533 80
e5998677 81=head1 Performance Enhancements
79116533 82
e5998677
SH
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
79116533 85
e5998677 86[ List each enhancement as a =item entry ]
79116533 87
e5998677 88=over 4
79116533
SH
89
90=item *
91
e5998677 92XXX
79116533
SH
93
94=back
0939a951 95
e5998677 96=head1 Modules and Pragmata
fea59588 97
e5998677
SH
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.
fea59588 103
e5998677 104[ Within each section, list entries as a =item entry ]
83a5d6b6 105
e5998677 106=head2 New Modules and Pragmata
83a5d6b6 107
e5998677 108=over 4
338906ce
SH
109
110=item *
111
e5998677 112XXX
b05565aa 113
e5998677 114=back
83a5d6b6 115
e5998677 116=head2 Updated Modules and Pragmata
83a5d6b6 117
e5998677 118=over 4
e455391f
SH
119
120=item *
121
53902397
SH
122L<Module::CoreList> has been upgraded from version 5.20150320 to 5.20150420.
123
124Updated to cover the latest releases of Perl.
83a5d6b6 125
abec5bed
DIM
126=item *
127
128L<ExtUtils::Miniperl> has been upgraded from version 1.04 to 1.05.
129
130=item *
131
132FindExt has been upgraded from version 1.02 to 1.03.
133
134=item *
135
136L<Cwd> has been upgraded from version 3.55 to 3.56.
137
138=item *
139
140L<PerlIO::mmap> has been upgraded from version 0.013 to 0.014.
141
142=item *
143
144L<attributes> has been upgraded from version 0.26 to 0.27.
145
e5998677 146=back
83a5d6b6 147
e5998677 148=head2 Removed Modules and Pragmata
83a5d6b6 149
e5998677 150=over 4
83a5d6b6
SH
151
152=item *
153
e5998677 154XXX
83a5d6b6 155
e5998677 156=back
83a5d6b6 157
e5998677 158=head1 Documentation
83a5d6b6 159
e5998677
SH
160XXX Changes to files in F<pod/> go here. Consider grouping entries by
161file and be sure to link to the appropriate page, e.g. L<perlfunc>.
83a5d6b6 162
e5998677 163=head2 New Documentation
b367c45d 164
e5998677 165XXX Changes which create B<new> files in F<pod/> go here.
b367c45d 166
e5998677 167=head3 L<XXX>
b367c45d 168
e5998677 169XXX Description of the purpose of the new file here
338906ce 170
e5998677 171=head2 Changes to Existing Documentation
338906ce 172
e5998677
SH
173XXX Changes which significantly change existing files in F<pod/> go here.
174However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
175section.
83a5d6b6 176
e5998677 177=head3 L<XXX>
83a5d6b6 178
e5998677 179=over 4
83a5d6b6
SH
180
181=item *
182
e5998677 183XXX Description of the change here
83a5d6b6 184
e5998677 185=back
338906ce 186
e5998677 187=head1 Diagnostics
338906ce 188
e5998677
SH
189The following additions or changes have been made to diagnostic output,
190including warnings and fatal error messages. For the complete list of
191diagnostic messages, see L<perldiag>.
338906ce 192
e5998677
SH
193XXX New or changed warnings emitted by the core's C<C> code go here. Also
194include any changes in L<perldiag> that reconcile it to the C<C> code.
338906ce 195
e5998677 196=head2 New Diagnostics
9409f752 197
e5998677
SH
198XXX Newly added diagnostic messages go under here, separated into New Errors
199and New Warnings
9409f752 200
e5998677 201=head3 New Errors
03a97c81 202
e5998677 203=over 4
03a97c81
SH
204
205=item *
206
e5998677 207XXX L<message|perldiag/"message">
a790e348 208
e5998677 209=back
83a5d6b6 210
e5998677 211=head3 New Warnings
83a5d6b6 212
e5998677 213=over 4
126be117
JH
214
215=item *
216
e5998677 217XXX L<message|perldiag/"message">
83a5d6b6 218
a9c3e753 219=back
0939a951 220
e5998677 221=head2 Changes to Existing Diagnostics
d2fff9f6 222
e5998677 223XXX Changes (i.e. rewording) of diagnostic messages go here
e329daf3 224
cd7bac54 225=over 4
e329daf3 226
cd7bac54 227=item *
e329daf3 228
e5998677 229XXX Describe change here
83a5d6b6
SH
230
231=back
232
e5998677 233=head1 Utility Changes
83a5d6b6 234
e5998677
SH
235XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
236Most of these are built within the directory F<utils>.
83a5d6b6 237
e5998677
SH
238[ List utility changes as a =head2 entry for each utility and =item
239entries for each change
240Use L<XXX> with program names to get proper documentation linking. ]
83a5d6b6 241
e5998677 242=head2 L<XXX>
83a5d6b6
SH
243
244=over 4
245
246=item *
247
e5998677 248XXX
ba31029d 249
cd7bac54
S
250=back
251
e5998677 252=head1 Configuration and Compilation
cd7bac54 253
e5998677
SH
254XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
255go here. Any other changes to the Perl build process should be listed here.
256However, any platform-specific changes should be listed in the
257L</Platform Support> section, instead.
cd7bac54 258
e5998677 259[ List changes as a =item entry ].
cd7bac54
S
260
261=over 4
262
263=item *
264
e5998677 265XXX
cd7bac54
S
266
267=back
541e1e0d 268
a9c3e753 269=head1 Testing
cd7bac54 270
e5998677
SH
271XXX Any significant changes to the testing of a freshly built perl should be
272listed here. Changes which create B<new> files in F<t/> go here as do any
273large changes to the testing harness (e.g. when parallel testing was added).
274Changes to existing files in F<t/> aren't worth summarizing, although the bugs
275that they represent may be covered elsewhere.
276
277[ List each test improvement as a =item entry ]
278
b5d4d3b9 279=over 4
83b69bfd
DD
280
281=item *
282
e5998677 283XXX
13adb056 284
b5d4d3b9 285=back
391823f2 286
a9c3e753 287=head1 Platform Support
6c8457e9 288
e5998677 289XXX Any changes to platform support should be listed in the sections below.
fdcaecb7 290
e5998677
SH
291[ Within the sections, list each platform as a =item entry with specific
292changes as paragraphs below it. ]
ce1e892e 293
e5998677 294=head2 New Platforms
2af7c6b6 295
e5998677
SH
296XXX List any platforms that this version of perl compiles on, that previous
297versions did not. These will either be enabled by new files in the F<hints/>
298directories, or new subdirectories and F<README> files at the top level of the
299source tree.
8c847e66 300
2ff1ebfe 301=over 4
d345f487 302
e5998677 303=item XXX-some-platform
d345f487 304
e5998677 305XXX
cd7bac54 306
4dc623f0 307=back
353075a0 308
e5998677 309=head2 Discontinued Platforms
9f122eef 310
e5998677 311XXX List any platforms that this version of perl no longer compiles on.
2ec11c70 312
e5998677 313=over 4
2ec11c70 314
e5998677 315=item XXX-some-platform
2683609f 316
e5998677 317XXX
338906ce 318
4dc623f0 319=back
c7f058f0 320
e5998677 321=head2 Platform-Specific Notes
2bf83140 322
e5998677
SH
323XXX List any changes for specific platforms. This could include configuration
324and compilation changes or changes in portability/compatibility. However,
325changes within modules for platforms should generally be listed in the
326L</Modules and Pragmata> section.
041a5927 327
e5998677 328=over 4
041a5927 329
e5998677 330=item XXX-some-platform
69e954a5 331
e5998677 332XXX
69e954a5 333
e5998677 334=back
20b5e916 335
e5998677 336=head1 Internal Changes
d76c14eb 337
e5998677
SH
338XXX Changes which affect the interface available to C<XS> code go here. Other
339significant internal changes for future core maintainers should be noted as
340well.
d76c14eb 341
e5998677 342[ List each change as a =item entry ]
d547bad0 343
e5998677 344=over 4
d547bad0 345
8a95d307
FC
346=item *
347
e5998677 348XXX
8a95d307 349
e5998677 350=back
338906ce 351
e5998677 352=head1 Selected Bug Fixes
338906ce 353
e5998677
SH
354XXX Important bug fixes in the core language are summarized here. Bug fixes in
355files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
338906ce 356
e5998677 357[ List each fix as a =item entry ]
338906ce 358
e5998677 359=over 4
338906ce
SH
360
361=item *
362
e5998677 363XXX
2f304be9 364
a9c3e753 365=back
ea13b07e 366
a9c3e753 367=head1 Known Problems
b65adbec 368
e5998677
SH
369XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
370tests that had to be C<TODO>ed for the release would be noted here. Unfixed
371platform specific bugs also go here.
b94c7836 372
e5998677 373[ List each fix as a =item entry ]
ce1e892e
KW
374
375=over 4
376
377=item *
378
e5998677 379XXX
ce1e892e 380
e5998677 381=back
ce1e892e 382
e5998677 383=head1 Errata From Previous Releases
ce1e892e 384
e5998677 385=over 4
ce1e892e 386
e5998677 387=item *
ce1e892e 388
e5998677
SH
389XXX Add anything here that we forgot to add, or were mistaken about, in
390the perldelta of a previous release.
ce1e892e 391
a9c3e753 392=back
e3e8f263 393
e5998677 394=head1 Obituary
0d42058e 395
e5998677
SH
396XXX If any significant core contributor has died, we've added a short obituary
397here.
0d42058e 398
e5998677 399=head1 Acknowledgements
0d42058e 400
e5998677 401XXX Generate this with:
0d42058e 402
e5998677 403 perl Porting/acknowledgements.pl v5.21.10..HEAD
f5b73711 404
44691e6f
AB
405=head1 Reporting Bugs
406
e08634c5
SH
407If you find what you think is a bug, you might check the articles recently
408posted to the comp.lang.perl.misc newsgroup and the perl bug database at
e5998677
SH
409https://rt.perl.org/ . There may also be information at
410http://www.perl.org/ , the Perl Home Page.
44691e6f 411
e08634c5
SH
412If you believe you have an unreported bug, please run the L<perlbug> program
413included with your release. Be sure to trim your bug down to a tiny but
414sufficient test case. Your bug report, along with the output of C<perl -V>,
415will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
416
417If the bug you are reporting has security implications, which make it
e08634c5
SH
418inappropriate to send to a publicly archived mailing list, then please send it
419to perl5-security-report@perl.org. This points to a closed subscription
420unarchived mailing list, which includes all the core committers, who will be
421able to help assess the impact of issues, figure out a resolution, and help
f9001595 422co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
423platforms on which Perl is supported. Please only use this address for
424security issues in the Perl core, not for modules independently distributed on
425CPAN.
44691e6f
AB
426
427=head1 SEE ALSO
428
e08634c5
SH
429The F<Changes> file for an explanation of how to view exhaustive details on
430what changed.
44691e6f
AB
431
432The F<INSTALL> file for how to build Perl.
433
434The F<README> file for general stuff.
435
436The F<Artistic> and F<Copying> files for copyright information.
437
438=cut