This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Encode to CPAN version 2.67
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
4dc623f0
CBW
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.7
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
4dc623f0 12This document describes differences between the 5.21.6 release and the 5.21.7
238894db 13release.
c68523cb 14
4dc623f0
CBW
15If you are upgrading from an earlier release such as 5.21.5, first read
16L<perl5216delta>, which describes differences between 5.21.5 and 5.21.6.
8435afd1 17
4dc623f0 18=head1 Notice
4cad5dc8 19
4dc623f0 20XXX Any important notices here
518159a1 21
4dc623f0 22=head1 Core Enhancements
518159a1 23
4dc623f0
CBW
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.
518159a1 27
4dc623f0 28[ List each enhancement as a =head2 entry ]
518159a1 29
4dc623f0 30=head1 Security
fe609065 31
4dc623f0
CBW
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.
fe609065 35
4dc623f0 36[ List each security issue as a =head2 entry ]
295f7815 37
4dc623f0 38=head1 Incompatible Changes
295f7815 39
4dc623f0 40XXX For a release on a stable branch, this section aspires to be:
bb8c7e27 41
4dc623f0
CBW
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.
9f122eef 45
4dc623f0 46[ List each incompatible change as a =head2 entry ]
5cfa0642 47
4dc623f0 48=head1 Deprecations
5b306eef 49
4dc623f0 50XXX Any deprecated features, syntax, modules etc. should be listed here.
5b306eef 51
4dc623f0 52=head2 Module removals
ef7051ba 53
4dc623f0 54XXX Remove this section if inapplicable.
ef7051ba 55
4dc623f0
CBW
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.
b450ee68 60
4dc623f0
CBW
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.
b450ee68 64
4dc623f0
CBW
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.
1e461e16 69
4dc623f0 70=over
1e461e16 71
4dc623f0 72=item XXX
aa95859b 73
4dc623f0
CBW
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.
aa95859b 76
86372193 77=back
357205d5 78
4dc623f0 79[ List each other deprecation as a =head2 entry ]
6ed80d55 80
c0659f73
KW
81=head2 Setting C<${^ENCODING}> to anything but C<undef>
82
83This variable allows Perl scripts to be written in a non-ASCII,
84non-UTF-8 encoding. However, it affects all modules globally, leading
85to wrong answers and segmentation faults. New scripts should be written
86in UTF-8; old scripts should be converted to UTF-8, which is easily done
87with the L<encoding> pragma.
88
4dc623f0 89=head1 Performance Enhancements
6ed80d55 90
4dc623f0
CBW
91XXX Changes which enhance performance without changing behaviour go here.
92There may well be none in a stable release.
6ed80d55 93
4dc623f0 94[ List each enhancement as a =item entry ]
6ed80d55 95
4dc623f0 96=over 4
6ed80d55
CBW
97
98=item *
99
4dc623f0 100XXX
6ed80d55 101
4dc623f0 102=back
f4e81f96 103
4dc623f0 104=head1 Modules and Pragmata
bb6a367a 105
4dc623f0
CBW
106XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
107go here. If Module::CoreList is updated, generate an initial draft of the
108following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
109for important changes should then be added by hand. In an ideal world,
110dual-life modules would have a F<Changes> file that could be cribbed.
f348c3d8 111
4dc623f0 112[ Within each section, list entries as a =item entry ]
f348c3d8 113
4dc623f0 114=head2 New Modules and Pragmata
6ed80d55 115
4dc623f0 116=over 4
f348c3d8
A
117
118=item *
119
4dc623f0 120XXX
7635ad4d 121
4dc623f0 122=back
7635ad4d 123
4dc623f0 124=head2 Updated Modules and Pragmata
7635ad4d 125
4dc623f0 126=over 4
f348c3d8 127
6ed80d55 128=item *
f348c3d8 129
7de6b801
TC
130L<ExtUtils::ParseXS> has been upgraded from version 3.26 to 3.27.
131
132Only declare C<file> unused if we actually define it.
133
134Improve generated C<RETVAL> code generation to avoid repeated
135references to C<ST(0)>. [perl #123278]
f4eedc6b 136
190f5bb6
TC
137=item *
138
139The PathTools module collection has been upgraded from 3.52 to 3.53.
140
141Don't turn leading C<//> into C</> on Cygwin. [perl #122635]
142
4dc623f0 143=back
f4eedc6b 144
4dc623f0 145=head2 Removed Modules and Pragmata
f4eedc6b 146
4dc623f0 147=over 4
f348c3d8 148
6ed80d55
CBW
149=item *
150
4dc623f0 151XXX
f348c3d8 152
4dc623f0 153=back
f348c3d8 154
4dc623f0 155=head1 Documentation
f348c3d8 156
4dc623f0
CBW
157XXX Changes to files in F<pod/> go here. Consider grouping entries by
158file and be sure to link to the appropriate page, e.g. L<perlfunc>.
f348c3d8 159
4dc623f0 160=head2 New Documentation
f348c3d8 161
4dc623f0 162XXX Changes which create B<new> files in F<pod/> go here.
f348c3d8 163
4dc623f0 164=head3 L<XXX>
6ed80d55 165
4dc623f0 166XXX Description of the purpose of the new file here
f348c3d8 167
6ed80d55 168=head2 Changes to Existing Documentation
f348c3d8 169
4dc623f0
CBW
170XXX Changes which significantly change existing files in F<pod/> go here.
171However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
172section.
173
174=head3 L<XXX>
84d03adf 175
86372193 176=over 4
ff433f2d 177
4cd408ba
TC
178=item *
179
4dc623f0 180XXX Description of the change here
f348c3d8 181
86372193 182=back
f348c3d8 183
6ed80d55
CBW
184=head1 Diagnostics
185
186The following additions or changes have been made to diagnostic output,
187including warnings and fatal error messages. For the complete list of
188diagnostic messages, see L<perldiag>.
189
4dc623f0
CBW
190XXX New or changed warnings emitted by the core's C<C> code go here. Also
191include any changes in L<perldiag> that reconcile it to the C<C> code.
6ed80d55 192
4dc623f0 193=head2 New Diagnostics
f348c3d8 194
4dc623f0
CBW
195XXX Newly added diagnostic messages go under here, separated into New Errors
196and New Warnings
ab0b796c 197
4dc623f0 198=head3 New Errors
8c6180a9
KW
199
200=over 4
201
202=item *
203
4dc623f0 204XXX L<message|perldiag/"message">
ab0b796c 205
86372193 206=back
0561e60b 207
4dc623f0 208=head3 New Warnings
dd200dff 209
4dc623f0 210=over 4
dd200dff 211
73e793fc
FC
212=item *
213
4dc623f0 214XXX L<message|perldiag/"message">
73e793fc 215
8c6180a9
KW
216=back
217
86372193 218=head2 Changes to Existing Diagnostics
0561e60b 219
4dc623f0 220XXX Changes (i.e. rewording) of diagnostic messages go here
4a328228 221
4dc623f0 222=over 4
4cd408ba 223
1861205d
FC
224=item *
225
4dc623f0 226XXX Describe change here
1861205d 227
86372193 228=back
40a81b59 229
4dc623f0 230=head1 Utility Changes
2a395b86 231
4dc623f0
CBW
232XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
233Most of these are built within the directory F<utils>.
2a395b86 234
4dc623f0
CBW
235[ List utility changes as a =head2 entry for each utility and =item
236entries for each change
237Use L<XXX> with program names to get proper documentation linking. ]
12d22d1f 238
4dc623f0 239=head2 L<XXX>
2a395b86 240
8c8d6154 241=over 4
2a395b86
PM
242
243=item *
244
4dc623f0 245XXX
bb8c7e27 246
86372193 247=back
bb8c7e27 248
4dc623f0 249=head1 Configuration and Compilation
bb8c7e27 250
4dc623f0
CBW
251XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
252go here. Any other changes to the Perl build process should be listed here.
253However, any platform-specific changes should be listed in the
254L</Platform Support> section, instead.
aa292ef2 255
4dc623f0 256[ List changes as a =item entry ].
83b69bfd
DD
257
258=over 4
259
260=item *
261
4dc623f0 262XXX
13adb056 263
83b69bfd
DD
264=back
265
4dc623f0 266=head1 Testing
391823f2 267
4dc623f0
CBW
268XXX Any significant changes to the testing of a freshly built perl should be
269listed here. Changes which create B<new> files in F<t/> go here as do any
270large changes to the testing harness (e.g. when parallel testing was added).
271Changes to existing files in F<t/> aren't worth summarizing, although the bugs
272that they represent may be covered elsewhere.
6ff8f256 273
4dc623f0 274[ List each test improvement as a =item entry ]
80cc3290 275
86372193 276=over 4
db98db4e 277
8818afe8
TC
278=item *
279
4dc623f0 280XXX
9d22ccf6 281
4dc623f0 282=back
480961b6 283
4dc623f0 284=head1 Platform Support
480961b6 285
4dc623f0 286XXX Any changes to platform support should be listed in the sections below.
94c9bf90 287
4dc623f0
CBW
288[ Within the sections, list each platform as a =item entry with specific
289changes as paragraphs below it. ]
94c9bf90 290
4dc623f0 291=head2 New Platforms
8af808bf 292
4dc623f0
CBW
293XXX List any platforms that this version of perl compiles on, that previous
294versions did not. These will either be enabled by new files in the F<hints/>
295directories, or new subdirectories and F<README> files at the top level of the
296source tree.
8af808bf 297
4dc623f0 298=over 4
fdcaecb7 299
4dc623f0 300=item XXX-some-platform
fdcaecb7 301
4dc623f0 302XXX
2af7c6b6 303
4dc623f0 304=back
2af7c6b6 305
4dc623f0 306=head2 Discontinued Platforms
c0b32823 307
4dc623f0 308XXX List any platforms that this version of perl no longer compiles on.
c0b32823 309
4dc623f0 310=over 4
b1a4e8b3 311
4dc623f0 312=item XXX-some-platform
b1a4e8b3 313
4dc623f0 314XXX
9e26817d 315
4dc623f0 316=back
9e26817d 317
4dc623f0 318=head2 Platform-Specific Notes
70cee83f 319
4dc623f0
CBW
320XXX List any changes for specific platforms. This could include configuration
321and compilation changes or changes in portability/compatibility. However,
322changes within modules for platforms should generally be listed in the
323L</Modules and Pragmata> section.
70cee83f 324
4dc623f0 325=over 4
e5fbfbc1 326
4dc623f0 327=item XXX-some-platform
e5fbfbc1 328
4dc623f0 329XXX
353075a0 330
4dc623f0 331=back
353075a0 332
4dc623f0 333=head1 Internal Changes
9f122eef 334
4dc623f0
CBW
335XXX Changes which affect the interface available to C<XS> code go here. Other
336significant internal changes for future core maintainers should be noted as
337well.
9f122eef 338
4dc623f0 339[ List each change as a =item entry ]
9f122eef 340
4dc623f0 341=over 4
9f122eef
FC
342
343=item *
344
4dc623f0 345XXX
c7f058f0 346
4dc623f0 347=back
c7f058f0 348
4dc623f0 349=head1 Selected Bug Fixes
0ef4323a 350
4dc623f0
CBW
351XXX Important bug fixes in the core language are summarized here. Bug fixes in
352files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
0ef4323a 353
4dc623f0 354[ List each fix as a =item entry ]
c263379c 355
4dc623f0 356=over 4
c263379c 357
ff90be78
TC
358=item *
359
452466a5
FC
360On Win32, restoring in a child pseudo-process a variable that was
361C<local()>ed in a parent pseudo-process before the C<fork> happened caused
362memory corruption and a crash in the child pseudo-process (and therefore OS
363process).
ff90be78 364
3e669301
KW
365=item *
366
367The L<encoding> pragma's effect is now limited to lexical scope. This
368pragma is deprecated, but in the meantime, it could adversely affect
369unrelated modules that are included in the same program.
370
86372193 371=back
bb8c7e27 372
86372193 373=head1 Known Problems
bb8c7e27 374
4dc623f0
CBW
375XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
376tests that had to be C<TODO>ed for the release would be noted here. Unfixed
377platform specific bugs also go here.
28a42920 378
4dc623f0 379[ List each fix as a =item entry ]
28a42920 380
6ed80d55
CBW
381=over 4
382
383=item *
384
4dc623f0 385XXX
6ed80d55
CBW
386
387=back
388
86372193 389=head1 Errata From Previous Releases
28a42920 390
86372193 391=over 4
28a42920
A
392
393=item *
394
4dc623f0
CBW
395XXX Add anything here that we forgot to add, or were mistaken about, in
396the perldelta of a previous release.
f5630681 397
8c8d6154 398=back
3a085d00 399
4dc623f0 400=head1 Obituary
01d42a22 401
4dc623f0
CBW
402XXX If any significant core contributor has died, we've added a short obituary
403here.
6ed80d55 404
4dc623f0 405=head1 Acknowledgements
01d42a22 406
4dc623f0 407XXX Generate this with:
01d42a22 408
4dc623f0 409 perl Porting/acknowledgements.pl v5.21.6..HEAD
f5b73711 410
44691e6f
AB
411=head1 Reporting Bugs
412
e08634c5
SH
413If you find what you think is a bug, you might check the articles recently
414posted to the comp.lang.perl.misc newsgroup and the perl bug database at
238894db 415https://rt.perl.org/ . There may also be information at
7ef8b31d 416http://www.perl.org/ , the Perl Home Page.
44691e6f 417
e08634c5
SH
418If you believe you have an unreported bug, please run the L<perlbug> program
419included with your release. Be sure to trim your bug down to a tiny but
420sufficient test case. Your bug report, along with the output of C<perl -V>,
421will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
422
423If the bug you are reporting has security implications, which make it
e08634c5
SH
424inappropriate to send to a publicly archived mailing list, then please send it
425to perl5-security-report@perl.org. This points to a closed subscription
426unarchived mailing list, which includes all the core committers, who will be
427able to help assess the impact of issues, figure out a resolution, and help
f9001595 428co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
429platforms on which Perl is supported. Please only use this address for
430security issues in the Perl core, not for modules independently distributed on
431CPAN.
44691e6f
AB
432
433=head1 SEE ALSO
434
e08634c5
SH
435The F<Changes> file for an explanation of how to view exhaustive details on
436what changed.
44691e6f
AB
437
438The F<INSTALL> file for how to build Perl.
439
440The F<README> file for general stuff.
441
442The F<Artistic> and F<Copying> files for copyright information.
443
444=cut