This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix up Peek.t after priv flag twiddling
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
39c4a6cf
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.21.4
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
39c4a6cf 12This document describes differences between the 5.21.3 release and the 5.21.4
238894db 13release.
c68523cb 14
39c4a6cf
PM
15If you are upgrading from an earlier release such as 5.21.2, first read
16L<perl5213delta>, which describes differences between 5.21.2 and 5.21.3.
7065301c 17
39c4a6cf 18=head1 Notice
7e957246 19
39c4a6cf 20XXX Any important notices here
7e957246 21
39c4a6cf 22=head1 Core Enhancements
f88f10f5 23
39c4a6cf
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.
21f3b41e 27
39c4a6cf 28[ List each enhancement as a =head2 entry ]
f88f10f5 29
0346c3a9 30=head1 Security
7e957246 31
39c4a6cf
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.
13900f93 35
39c4a6cf 36[ List each security issue as a =head2 entry ]
8bdb3f93 37
13900f93 38=head1 Incompatible Changes
8bdb3f93 39
39c4a6cf 40XXX For a release on a stable branch, this section aspires to be:
1178d2cf 41
39c4a6cf
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.
1178d2cf 45
39c4a6cf 46[ List each incompatible change as a =head2 entry ]
f6f3144e 47
39c4a6cf 48=head1 Deprecations
7065301c 49
39c4a6cf 50XXX Any deprecated features, syntax, modules etc. should be listed here.
7065301c 51
39c4a6cf 52=head2 Module removals
b3e82ed1 53
39c4a6cf 54XXX Remove this section if inapplicable.
ca58223b 55
39c4a6cf
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.
ca58223b 60
39c4a6cf
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.
23b03637 64
39c4a6cf
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.
23b03637 69
39c4a6cf 70=over
85e8fb10 71
39c4a6cf 72=item XXX
85e8fb10 73
39c4a6cf
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.
134f90c2 76
39c4a6cf 77=back
134f90c2 78
39c4a6cf 79[ List each other deprecation as a =head2 entry ]
ff433f2d 80
39c4a6cf 81=head1 Performance Enhancements
ff433f2d 82
39c4a6cf
PM
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
134f90c2 85
39c4a6cf 86[ List each enhancement as a =item entry ]
134f90c2 87
39c4a6cf 88=over 4
7d19f6a1 89
7d19f6a1
PM
90=item *
91
39c4a6cf 92XXX
55e8b286 93
39c4a6cf 94=back
55e8b286 95
39c4a6cf 96=head1 Modules and Pragmata
d99849ae 97
39c4a6cf
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.
d99849ae 103
39c4a6cf 104[ Within each section, list entries as a =item entry ]
ff433f2d 105
39c4a6cf 106=head2 New Modules and Pragmata
ff433f2d 107
39c4a6cf 108=over 4
ff433f2d
PM
109
110=item *
111
39c4a6cf 112XXX
0bb39c26 113
39c4a6cf 114=back
0bb39c26 115
39c4a6cf 116=head2 Updated Modules and Pragmata
9c97a342 117
39c4a6cf 118=over 4
d99849ae
PM
119
120=item *
121
39c4a6cf 122L<XXX> has been upgraded from version A.xx to B.yy.
6ab3666b 123
39c4a6cf 124=back
9c97a342 125
39c4a6cf 126=head2 Removed Modules and Pragmata
d99849ae 127
39c4a6cf 128=over 4
d99849ae 129
ff433f2d
PM
130=item *
131
39c4a6cf 132XXX
ff433f2d 133
13900f93 134=back
aac7f82f 135
13900f93 136=head1 Documentation
aac7f82f 137
39c4a6cf
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>.
6d9b7c7c 140
39c4a6cf 141=head2 New Documentation
2a395b86 142
39c4a6cf 143XXX Changes which create B<new> files in F<pod/> go here.
2a395b86 144
39c4a6cf 145=head3 L<XXX>
2a395b86 146
39c4a6cf 147XXX Description of the purpose of the new file here
2a395b86 148
39c4a6cf 149=head2 Changes to Existing Documentation
2a395b86 150
39c4a6cf
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.
154
155=head3 L<XXX>
2a395b86
PM
156
157=over 4
158
159=item *
160
39c4a6cf 161XXX Description of the change here
2a395b86
PM
162
163=back
164
39c4a6cf 165=head1 Diagnostics
2a395b86 166
39c4a6cf
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>.
2a395b86 170
39c4a6cf
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.
2a395b86 173
39c4a6cf 174=head2 New Diagnostics
0f4a583b 175
39c4a6cf
PM
176XXX Newly added diagnostic messages go under here, separated into New Errors
177and New Warnings
2a395b86 178
39c4a6cf 179=head3 New Errors
2a395b86
PM
180
181=over 4
182
183=item *
184
39c4a6cf 185XXX L<message|perldiag/"message">
2a395b86
PM
186
187=back
188
39c4a6cf 189=head3 New Warnings
2a395b86
PM
190
191=over 4
192
193=item *
194
39c4a6cf 195XXX L<message|perldiag/"message">
2a395b86
PM
196
197=back
6d9b7c7c 198
39c4a6cf
PM
199=head2 Changes to Existing Diagnostics
200
201XXX Changes (i.e. rewording) of diagnostic messages go here
7f55cec0 202
13900f93 203=over 4
7f55cec0
SH
204
205=item *
206
39c4a6cf 207XXX Describe change here
aac7f82f 208
13900f93 209=back
aac7f82f 210
39c4a6cf 211=head1 Utility Changes
091fed7c 212
39c4a6cf
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>.
902c1f75 215
39c4a6cf
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. ]
2901561d 219
39c4a6cf 220=head2 L<XXX>
4594cf53 221
13900f93 222=over 4
96dcbc37
DD
223
224=item *
225
39c4a6cf 226XXX
a1d26ccd 227
39c4a6cf 228=back
a1d26ccd 229
39c4a6cf 230=head1 Configuration and Compilation
7065301c 231
39c4a6cf
PM
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.
58f25ac1 236
39c4a6cf 237[ List changes as a =item entry ].
13900f93
A
238
239=over 4
58f25ac1
MH
240
241=item *
242
39c4a6cf 243XXX
a5873648 244
39c4a6cf 245=back
a5873648 246
39c4a6cf 247=head1 Testing
a5873648 248
39c4a6cf
PM
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.
a5873648 254
39c4a6cf 255[ List each test improvement as a =item entry ]
a5873648 256
39c4a6cf 257=over 4
a5873648
PM
258
259=item *
260
39c4a6cf 261XXX
a5873648 262
58f25ac1
MH
263=back
264
39c4a6cf 265=head1 Platform Support
b10906fb 266
39c4a6cf 267XXX Any changes to platform support should be listed in the sections below.
b10906fb 268
39c4a6cf
PM
269[ Within the sections, list each platform as a =item entry with specific
270changes as paragraphs below it. ]
b10906fb 271
39c4a6cf 272=head2 New Platforms
b10906fb 273
39c4a6cf
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.
13900f93 278
7065301c 279=over 4
24a38d90 280
39c4a6cf 281=item XXX-some-platform
24a38d90 282
39c4a6cf 283XXX
bb076206 284
7065301c
RS
285=back
286
39c4a6cf 287=head2 Discontinued Platforms
097675bf 288
39c4a6cf 289XXX List any platforms that this version of perl no longer compiles on.
b3211734 290
6e97d65d 291=over 4
b3211734 292
39c4a6cf 293=item XXX-some-platform
7065301c 294
39c4a6cf 295XXX
13900f93 296
39c4a6cf 297=back
7d0ccdba 298
39c4a6cf 299=head2 Platform-Specific Notes
7d0ccdba 300
39c4a6cf
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.
6e97d65d 305
39c4a6cf 306=over 4
6e97d65d 307
39c4a6cf 308=item XXX-some-platform
6e97d65d 309
39c4a6cf 310XXX
7d0ccdba 311
7065301c
RS
312=back
313
314=head1 Internal Changes
315
39c4a6cf
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.
c9fcb674 319
39c4a6cf 320[ List each change as a =item entry ]
a835cd47 321
39c4a6cf 322=over 4
c1284011 323
1c43698b
PM
324=item *
325
39c4a6cf 326XXX
1c43698b 327
6d9b7c7c 328=back
c1284011 329
6d9b7c7c 330=head1 Selected Bug Fixes
375f5f06 331
39c4a6cf
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>.
334
335[ List each fix as a =item entry ]
336
0346c3a9 337=over 4
375f5f06 338
2884baee
MH
339=item *
340
39c4a6cf 341XXX
2884baee 342
39c4a6cf 343=back
b756670b 344
39c4a6cf 345=head1 Known Problems
b756670b 346
39c4a6cf
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.
e917e94e 350
39c4a6cf
PM
351[ List each fix as a =item entry ]
352
353=over 4
e917e94e 354
26dd5fd6
PM
355=item *
356
39c4a6cf 357XXX
26dd5fd6 358
13900f93
A
359=back
360
39c4a6cf 361=head1 Errata From Previous Releases
e831f11a 362
39c4a6cf
PM
363=over 4
364
365=item *
ff433f2d 366
39c4a6cf
PM
367XXX Add anything here that we forgot to add, or were mistaken about, in
368the perldelta of a previous release.
ff433f2d 369
39c4a6cf
PM
370=back
371
372=head1 Obituary
ff433f2d 373
39c4a6cf
PM
374XXX If any significant core contributor has died, we've added a short obituary
375here.
ff433f2d 376
39c4a6cf 377=head1 Acknowledgements
ff433f2d 378
39c4a6cf 379XXX Generate this with:
e831f11a 380
39c4a6cf 381 perl Porting/acknowledgements.pl v5.21.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
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