This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix win32 test failures
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
3ce6a296
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.25.9
eabfc7bc 9
2cfe9b50 10=head1 DESCRIPTION
eabfc7bc 11
3ce6a296 12This document describes differences between the 5.25.8 release and the 5.25.9
4b8803f0 13release.
f3ed8cbf 14
3ce6a296
S
15If you are upgrading from an earlier release such as 5.25.7, first read
16L<perl5258delta>, which describes differences between 5.25.7 and 5.25.8.
17
18=head1 Notice
19
20XXX Any important notices here
8bbdbfcb 21
733dba2b 22=head1 Core Enhancements
ce6646d7 23
3ce6a296
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.
27
28[ List each enhancement as a =head2 entry ]
29
30=head1 Security
31
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.
35
36[ List each security issue as a =head2 entry ]
37
38=head1 Incompatible Changes
39
40XXX For a release on a stable branch, this section aspires to be:
41
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.
45
46[ List each incompatible change as a =head2 entry ]
47
48=head1 Deprecations
49
94749a5e
KW
50=head2 String delimiters that aren't stand-alone graphemes are now
51deprecated
52
53In order for Perl to eventually allow string delimiters to be Unicode
54grapheme clusters (which look like a single character, but may be
55a sequence of several ones), we have to stop allowing a single char
56delimiter that isn't a grapheme by itself. These are unlikely to exist
57in actual code, as they would typically display as attached to the
58character in front of them.
3ce6a296
S
59
60=head2 Module removals
61
62XXX Remove this section if inapplicable.
63
64The following modules will be removed from the core distribution in a
65future release, and will at that time need to be installed from CPAN.
66Distributions on CPAN which require these modules will need to list them as
67prerequisites.
68
69The core versions of these modules will now issue C<"deprecated">-category
70warnings to alert you to this fact. To silence these deprecation warnings,
71install the modules in question from CPAN.
72
73Note that these are (with rare exceptions) fine modules that you are encouraged
74to continue to use. Their disinclusion from core primarily hinges on their
75necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
76not usually on concerns over their design.
eaed4a85 77
3ce6a296 78=over
eaed4a85 79
3ce6a296
S
80=item XXX
81
82XXX Note that deprecated modules should be listed here even if they are listed
83as an updated module in the L</Modules and Pragmata> section.
84
85=back
86
87[ List each other deprecation as a =head2 entry ]
eaed4a85 88
733dba2b 89=head1 Performance Enhancements
226eba01 90
3ce6a296
S
91XXX Changes which enhance performance without changing behaviour go here.
92There may well be none in a stable release.
8bbdbfcb 93
3ce6a296 94[ List each enhancement as a =item entry ]
8bbdbfcb 95
3ce6a296 96=over 4
8bbdbfcb 97
3ce6a296 98=item *
dd3d2a3f 99
3ce6a296 100XXX
dd3d2a3f 101
8bbdbfcb
CG
102=back
103
733dba2b 104=head1 Modules and Pragmata
8bbdbfcb 105
3ce6a296
S
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.
111
112[ Within each section, list entries as a =item entry ]
113
114=head2 New Modules and Pragmata
8bbdbfcb
CG
115
116=over 4
117
118=item *
119
3ce6a296 120XXX
8bbdbfcb 121
3ce6a296
S
122=back
123
124=head2 Updated Modules and Pragmata
ff10d69b 125
3ce6a296 126=over 4
ff10d69b 127
76ea8b6a
JK
128=item *
129
3ce6a296 130L<XXX> has been upgraded from version A.xx to B.yy.
8bbdbfcb 131
d4151a23
S
132=item *
133
59aeb939 134L<Module::CoreList> has been upgraded from version 5.20161220 to 5.20170120.
d4151a23 135
3ce6a296 136=back
8bbdbfcb 137
3ce6a296
S
138=head2 Removed Modules and Pragmata
139
140=over 4
8bbdbfcb
CG
141
142=item *
143
3ce6a296 144XXX
8bbdbfcb 145
3ce6a296 146=back
8bbdbfcb 147
3ce6a296 148=head1 Documentation
8bbdbfcb 149
3ce6a296
S
150XXX Changes to files in F<pod/> go here. Consider grouping entries by
151file and be sure to link to the appropriate page, e.g. L<perlfunc>.
8bbdbfcb 152
3ce6a296 153=head2 New Documentation
8bbdbfcb 154
3ce6a296 155XXX Changes which create B<new> files in F<pod/> go here.
8bbdbfcb 156
3ce6a296 157=head3 L<XXX>
8bbdbfcb 158
3ce6a296 159XXX Description of the purpose of the new file here
8bbdbfcb 160
3ce6a296 161=head2 Changes to Existing Documentation
8bbdbfcb 162
3ce6a296
S
163XXX Changes which significantly change existing files in F<pod/> go here.
164However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
165section.
166
167=head3 L<XXX>
8bbdbfcb 168
3ce6a296 169=over 4
8bbdbfcb 170
107db227 171=item *
8bbdbfcb 172
3ce6a296 173XXX Description of the change here
8bbdbfcb 174
3ce6a296 175=back
8bbdbfcb 176
3ce6a296 177=head1 Diagnostics
8bbdbfcb 178
3ce6a296
S
179The following additions or changes have been made to diagnostic output,
180including warnings and fatal error messages. For the complete list of
181diagnostic messages, see L<perldiag>.
182
183XXX New or changed warnings emitted by the core's C<C> code go here. Also
184include any changes in L<perldiag> that reconcile it to the C<C> code.
8c3f6b0b 185
3ce6a296
S
186=head2 New Diagnostics
187
188XXX Newly added diagnostic messages go under here, separated into New Errors
189and New Warnings
190
191=head3 New Errors
192
193=over 4
a09f502b 194
107db227 195=item *
2c4879e2 196
3ce6a296
S
197XXX L<message|perldiag/"message">
198
199=back
200
201=head3 New Warnings
202
203=over 4
8bbdbfcb
CG
204
205=item *
206
3ce6a296
S
207XXX L<message|perldiag/"message">
208
209=back
210
211=head2 Changes to Existing Diagnostics
212
213XXX Changes (i.e. rewording) of diagnostic messages go here
214
215=over 4
bd5630ab 216
107db227 217=item *
2c4879e2 218
3ce6a296
S
219XXX Describe change here
220
221=back
222
223=head1 Utility Changes
224
225XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
226Most of these are built within the directory F<utils>.
227
228[ List utility changes as a =head2 entry for each utility and =item
229entries for each change
230Use L<XXX> with program names to get proper documentation linking. ]
231
232=head2 L<XXX>
233
234=over 4
a09f502b 235
107db227 236=item *
8bbdbfcb 237
3ce6a296
S
238XXX
239
240=back
241
242=head1 Configuration and Compilation
243
244XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
245go here. Any other changes to the Perl build process should be listed here.
246However, any platform-specific changes should be listed in the
247L</Platform Support> section, instead.
248
249[ List changes as a =item entry ].
250
251=over 4
8bbdbfcb 252
107db227 253=item *
8bbdbfcb 254
3ce6a296
S
255XXX
256
257=back
258
259=head1 Testing
260
261XXX Any significant changes to the testing of a freshly built perl should be
262listed here. Changes which create B<new> files in F<t/> go here as do any
263large changes to the testing harness (e.g. when parallel testing was added).
264Changes to existing files in F<t/> aren't worth summarizing, although the bugs
265that they represent may be covered elsewhere.
266
267[ List each test improvement as a =item entry ]
268
269=over 4
8bbdbfcb
CG
270
271=item *
272
3ce6a296 273XXX
07cfdfcc 274
262514fd 275=back
2c4879e2 276
3ce6a296
S
277=head1 Platform Support
278
279XXX Any changes to platform support should be listed in the sections below.
280
281[ Within the sections, list each platform as a =item entry with specific
282changes as paragraphs below it. ]
283
284=head2 New Platforms
285
286XXX List any platforms that this version of perl compiles on, that previous
287versions did not. These will either be enabled by new files in the F<hints/>
288directories, or new subdirectories and F<README> files at the top level of the
289source tree.
290
291=over 4
292
293=item XXX-some-platform
294
295XXX
296
297=back
298
299=head2 Discontinued Platforms
300
301XXX List any platforms that this version of perl no longer compiles on.
302
303=over 4
304
305=item XXX-some-platform
306
307XXX
308
309=back
310
311=head2 Platform-Specific Notes
312
313XXX List any changes for specific platforms. This could include configuration
314and compilation changes or changes in portability/compatibility. However,
315changes within modules for platforms should generally be listed in the
316L</Modules and Pragmata> section.
317
318=over 4
319
320=item XXX-some-platform
321
322XXX
323
324=back
325
326=head1 Internal Changes
327
328XXX Changes which affect the interface available to C<XS> code go here. Other
329significant internal changes for future core maintainers should be noted as
330well.
331
332[ List each change as a =item entry ]
a09f502b 333
733dba2b 334=over 4
a09f502b 335
a07f6112 336=item *
a09f502b 337
a239b1e2
KW
338New versions of macros like C<isALPHA_utf8> and C<toLOWER_utf8> have
339been added, each with the
da8c1a98
KW
340suffix C<_safe>, like C<isSPACE_utf8_safe>. These take an extra
341parameter, giving an upper limit of how far into the string it is safe
342to read. Using the old versions could cause attempts to read beyond the
607313a1
KW
343end of the input buffer if the UTF-8 is not well-formed, and ther use
344now raises a deprecation warning. Details are at
da8c1a98
KW
345L<perlapi/Character classification>.
346
347=item *
348
86ae6e94
KW
349Calling macros like C<isALPHA_utf8> on malformed UTF-8 have issued a
350deprecation warning since Perl v5.18. They now die.
fa8ab374 351Similarly, macros like C<toLOWER_utf8> on malformed UTF-8 now die.
3ce6a296 352
d1f8d421
KW
353=item *
354
355Calling the functions C<utf8n_to_uvchr> and its derivatives, while
5a48568d
KW
356passing a string length of 0 is now asserted against in DEBUGGING
357builds, and otherwise returns the Unicode REPLACEMENT CHARACTER. If
358you have nothing to decode, you shouldn't call the decode function.
d1f8d421 359
94953955
KW
360=item *
361
362The functions C<utf8n_to_uvchr> and its derivatives now return the
363Unicode REPLACEMENT CHARACTER if called with UTF-8 that has the overlong
364malformation, and that malformation is allowed by the input parameters.
365This malformation is where the UTF-8 looks valid syntactically, but
366there is a shorter sequence that yields the same code point. This has
367been forbidden since Unicode version 3.1.
368
d60baaa7
KW
369=item *
370
371The functions C<utf8n_to_uvchr> and its derivatives now accept an input
372flag to allow the overflow malformation. This malformation is when the
373UTF-8 may be syntactically valid, but the code point it represents is
374not capable of being represented in the word length on the platform.
375What "allowed" means in this case is that the function doesn't return an
376error, and advances the parse pointer to beyond the UTF-8 in question,
377but it returns the Unicode REPLACEMENT CHARACTER as the value of the
378code point (since the real value is not representable).
379
3ce6a296
S
380=back
381
382=head1 Selected Bug Fixes
383
384XXX Important bug fixes in the core language are summarized here. Bug fixes in
385files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
386
387[ List each fix as a =item entry ]
388
389=over 4
a09f502b 390
36cabe94
YO
391=item *
392
6cdc5cd8
KW
393Under C<use utf8>, the entire Perl program is now checked that the UTF-8
394is wellformed. This resolves [perl #126310].
3ce6a296
S
395
396=back
397
398=head1 Known Problems
399
400XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
401tests that had to be C<TODO>ed for the release would be noted here. Unfixed
402platform specific bugs also go here.
36cabe94 403
3ce6a296
S
404[ List each fix as a =item entry ]
405
406=over 4
407
408=item *
409
410XXX
36cabe94 411
a07f6112 412=back
7d897bd0 413
3ce6a296
S
414=head1 Errata From Previous Releases
415
416=over 4
8bbdbfcb 417
3ce6a296
S
418=item *
419
420XXX Add anything here that we forgot to add, or were mistaken about, in
421the perldelta of a previous release.
8bbdbfcb 422
3ce6a296 423=back
262514fd 424
3ce6a296 425=head1 Obituary
a6a32e96 426
3ce6a296
S
427XXX If any significant core contributor has died, we've added a short obituary
428here.
262514fd 429
3ce6a296 430=head1 Acknowledgements
226eba01 431
3ce6a296 432XXX Generate this with:
24528e8e 433
3ce6a296 434 perl Porting/acknowledgements.pl v5.25.5..HEAD
f5b73711 435
44691e6f
AB
436=head1 Reporting Bugs
437
c0ea3294
SH
438If you find what you think is a bug, you might check the perl bug database
439at L<https://rt.perl.org/> . There may also be information at
4b8803f0 440L<http://www.perl.org/> , the Perl Home Page.
44691e6f 441
e08634c5
SH
442If you believe you have an unreported bug, please run the L<perlbug> program
443included with your release. Be sure to trim your bug down to a tiny but
444sufficient test case. Your bug report, along with the output of C<perl -V>,
445will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 446
87c118b9
DM
447If the bug you are reporting has security implications which make it
448inappropriate to send to a publicly archived mailing list, then see
c0ea3294
SH
449L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
450for details of how to report the issue.
44691e6f
AB
451
452=head1 SEE ALSO
453
e08634c5
SH
454The F<Changes> file for an explanation of how to view exhaustive details on
455what changed.
44691e6f
AB
456
457The F<INSTALL> file for how to build Perl.
458
459The F<README> file for general stuff.
460
461The F<Artistic> and F<Copying> files for copyright information.
462
463=cut