This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
8e1542325438d8d75402bd68caf705fad0328fce
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.21.11
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.21.10 release and the 5.21.11
13 release.
14
15 If you are upgrading from an earlier release such as 5.21.9, first read
16 L<perl52110delta>, which describes differences between 5.21.9 and 5.21.10.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head1 Security
31
32 XXX Any security-related notices go here.  In particular, any security
33 vulnerabilities closed should be noted here rather than in the
34 L</Selected Bug Fixes> section.
35
36 [ List each security issue as a =head2 entry ]
37
38 =head1 Incompatible Changes
39
40 XXX 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
50 XXX Any deprecated features, syntax, modules etc. should be listed here.
51
52 =head2 Making all warnings fatal is discouraged
53
54 The documentation for L<fatal warnings|warnings/Fatal Warnings> notes
55 that C<< use warnings FATAL => 'all' >> is discouraged
56 and provides stronger language about the risks of fatal warnings
57 in general.
58
59 =head2 Module removals
60
61 XXX Remove this section if inapplicable.
62
63 The following modules will be removed from the core distribution in a
64 future release, and will at that time need to be installed from CPAN.
65 Distributions on CPAN which require these modules will need to list them as
66 prerequisites.
67
68 The core versions of these modules will now issue C<"deprecated">-category
69 warnings to alert you to this fact.  To silence these deprecation warnings,
70 install the modules in question from CPAN.
71
72 Note that these are (with rare exceptions) fine modules that you are encouraged
73 to continue to use.  Their disinclusion from core primarily hinges on their
74 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
75 not usually on concerns over their design.
76
77 =over
78
79 =item XXX
80
81 XXX Note that deprecated modules should be listed here even if they are listed
82 as an updated module in the L</Modules and Pragmata> section.
83
84 =back
85
86 [ List each other deprecation as a =head2 entry ]
87
88 =head1 Performance Enhancements
89
90 XXX Changes which enhance performance without changing behaviour go here.
91 There may well be none in a stable release.
92
93 [ List each enhancement as a =item entry ]
94
95 =over 4
96
97 =item *
98
99 XXX
100
101 =back
102
103 =head1 Modules and Pragmata
104
105 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
106 go here.  If Module::CoreList is updated, generate an initial draft of the
107 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
108 for important changes should then be added by hand.  In an ideal world,
109 dual-life modules would have a F<Changes> file that could be cribbed.
110
111 [ Within each section, list entries as a =item entry ]
112
113 =head2 New Modules and Pragmata
114
115 =over 4
116
117 =item *
118
119 XXX
120
121 =back
122
123 =head2 Updated Modules and Pragmata
124
125 =over 4
126
127 =item *
128
129 L<attributes> has been upgraded from version 0.26 to 0.27.
130
131 =item *
132
133 L<B> has been upgraded from version 1.57 to 1.58.
134
135 =item *
136
137 L<B::Deparse> has been upgraded from version 1.34 to 1.35.
138
139 C<< <<>> >> is now correctly deparsed.
140
141 =item *
142
143 L<Config::Perl::V> has been upgraded from version 0.23 to 0.24.
144
145 =item *
146
147 L<Cwd> has been upgraded from version 3.55 to 3.56.
148
149 =item *
150
151 L<ExtUtils::Miniperl> has been upgraded from version 1.04 to 1.05.
152
153 =item *
154
155 L<ExtUtils::ParseXS> has been upgraded from version 3.27 to 3.28.
156
157 =item *
158
159 L<ExtUtils::Typemaps> has been upgraded from version 3.25 to 3.28.
160
161 =item *
162
163 L<File::Spec> has been upgraded from version 3.55 to 3.56.
164
165 =item *
166
167 L<if> has been upgraded from version 0.0603 to 0.0604.
168
169 =item *
170
171 L<IO::Socket::IP> has been upgraded from version 0.36 to 0.37.
172
173 =item *
174
175 L<Module::CoreList> has been upgraded from version 5.20150320 to 5.20150420.
176
177 Updated to cover the latest releases of Perl.
178
179 =item *
180
181 L<perl5db.pl> has been upgraded from 1.48 to 1.49.
182
183 The debugger would cause an assertion failure.  [perl #124127]
184
185 =item *
186
187 L<PerlIO::mmap> has been upgraded from version 0.013 to 0.014.
188
189 =item *
190
191 L<utf8> has been upgraded from version 1.15 to 1.16.
192
193 =item *
194
195 L<warnings> has been upgraded from version 1.31 to 1.32.
196
197 =back
198
199 =head2 Removed Modules and Pragmata
200
201 =over 4
202
203 =item *
204
205 XXX
206
207 =back
208
209 =head1 Documentation
210
211 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
212 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
213
214 =head2 New Documentation
215
216 XXX Changes which create B<new> files in F<pod/> go here.
217
218 =head3 L<XXX>
219
220 XXX Description of the purpose of the new file here
221
222 =head2 Changes to Existing Documentation
223
224 XXX Changes which significantly change existing files in F<pod/> go here.
225 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
226 section.
227
228 =head3 L<perlebcdic>
229
230 =over 4
231
232 =item *
233
234 This document has been significantly updated in the light of recent
235 improvements to EBCDIC support.
236
237 =back
238
239 =head3 L<perlfunc>
240
241 =over 4
242
243 =item *
244
245 Mention that C<study()> is currently a no-op.
246
247 =back
248
249 =head3 L<perlguts>
250
251 =over 4
252
253 =item *
254
255 The OOK example has been updated to account for COW changes and a change in the
256 storage of the offset.
257
258 =back
259
260 =head3 L<perlhacktips>
261
262 =over 4
263
264 =item *
265
266 Documentation has been added illustrating the perils of assuming the contents of
267 static memory pointed to by the return values of Perl wrappers for C library
268 functions doesn't change.
269
270 =back
271
272 =head3 L<perlvms>
273
274 =over 4
275
276 =item *
277
278 Out-of-date and/or incorrect material has been removed.
279
280 =back
281
282 =head1 Diagnostics
283
284 The following additions or changes have been made to diagnostic output,
285 including warnings and fatal error messages.  For the complete list of
286 diagnostic messages, see L<perldiag>.
287
288 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
289 include any changes in L<perldiag> that reconcile it to the C<C> code.
290
291 =head2 New Diagnostics
292
293 XXX Newly added diagnostic messages go under here, separated into New Errors
294 and New Warnings
295
296 =head3 New Errors
297
298 =over 4
299
300 =item *
301
302 XXX L<message|perldiag/"message">
303
304 =back
305
306 =head3 New Warnings
307
308 =over 4
309
310 =item *
311
312 XXX L<message|perldiag/"message">
313
314 =back
315
316 =head2 Changes to Existing Diagnostics
317
318 XXX Changes (i.e. rewording) of diagnostic messages go here
319
320 =over 4
321
322 =item *
323
324 XXX Describe change here
325
326 =back
327
328 =head1 Utility Changes
329
330 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
331 Most of these are built within the directory F<utils>.
332
333 [ List utility changes as a =head2 entry for each utility and =item
334 entries for each change
335 Use L<XXX> with program names to get proper documentation linking. ]
336
337 =head2 L<XXX>
338
339 =over 4
340
341 =item *
342
343 XXX
344
345 =back
346
347 =head1 Configuration and Compilation
348
349 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
350 go here.  Any other changes to the Perl build process should be listed here.
351 However, any platform-specific changes should be listed in the
352 L</Platform Support> section, instead.
353
354 [ List changes as a =item entry ].
355
356 =over 4
357
358 =item *
359
360 XXX
361
362 =back
363
364 =head1 Testing
365
366 XXX Any significant changes to the testing of a freshly built perl should be
367 listed here.  Changes which create B<new> files in F<t/> go here as do any
368 large changes to the testing harness (e.g. when parallel testing was added).
369 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
370 that they represent may be covered elsewhere.
371
372 [ List each test improvement as a =item entry ]
373
374 =over 4
375
376 =item *
377
378 F<t/porting/re_context.t> has been added to test that L<utf8> and its
379 dependencies only use the subset of the C<$1..$n> capture vars that
380 Perl_save_re_context() is hard-coded to localize, because that function has no
381 efficient way of determining at runtime what vars to localize.
382
383 =back
384
385 =head1 Platform Support
386
387 XXX Any changes to platform support should be listed in the sections below.
388
389 [ Within the sections, list each platform as a =item entry with specific
390 changes as paragraphs below it. ]
391
392 =head2 New Platforms
393
394 XXX List any platforms that this version of perl compiles on, that previous
395 versions did not.  These will either be enabled by new files in the F<hints/>
396 directories, or new subdirectories and F<README> files at the top level of the
397 source tree.
398
399 =over 4
400
401 =item XXX-some-platform
402
403 XXX
404
405 =back
406
407 =head2 Discontinued Platforms
408
409 XXX List any platforms that this version of perl no longer compiles on.
410
411 =over 4
412
413 =item XXX-some-platform
414
415 XXX
416
417 =back
418
419 =head2 Platform-Specific Notes
420
421 XXX List any changes for specific platforms.  This could include configuration
422 and compilation changes or changes in portability/compatibility.  However,
423 changes within modules for platforms should generally be listed in the
424 L</Modules and Pragmata> section.
425
426 =over 4
427
428 =item Win32
429
430 F<miniperl.exe> is now built with C<-fno-strict-aliasing>, allowing
431 64-bit builds to complete on GCC 4.8. [perl #123976]
432
433 C<test-prep> again depends on C<test-prep-gcc> for GCC builds. [perl
434 #124221]
435
436 =back
437
438 =head1 Internal Changes
439
440 =over 4
441
442 =item *
443
444 5.21.2 introduced a new build option, C<-DPERL_OP_PARENT>, which causes
445 the last C<op_sibling> pointer to refer back to the parent rather than
446 being C<NULL>, and where instead a new flag indicates the end of the
447 chain. In this release, the new implementation has been revised; in
448 particular:
449
450 =over 4
451
452 =item *
453
454 On C<PERL_OP_PARENT> builds, the C<op_sibling> field has been renamed
455 C<op_sibparent> to reflect its new dual purpose. Since the intention is that
456 this field should primarily be accessed via macros, this change should be
457 transparent for code written to work under C<PERL_OP_PARENT>.
458
459 =item *
460
461 The newly-introduced C<op_lastsib> flag bit has been renamed C<op_moresib>
462 and its logic inverted; i.e. it is initialised to zero in a new op, and is
463 changed to 1 when an op gains a sibling.
464
465 =item *
466
467 The function C<Perl_op_parent> is now only available on C<PERL_OP_PARENT>
468 builds. Using it on a plain build will be a compile-timer error.
469
470 =item *
471
472 Three new macros, C<OpMORESIB_set>, C<OpLASTSIB_set>, C<OpMAYBESIB_set>
473 have been added, which are intended to be be a low-level portable way to
474 set C<op_sibling> / C<op_sibparent> while also updating C<op_moresib>.
475 The first sets the sibling pointer to a new sibling, the second makes the
476 op the last sibling, and the third conditionally does the first or second
477 action. The C<op_sibling_splice()> function is retained as a higher-level
478 interface that can also maintain consistency in the parent at the same time
479 (e.g. by updating C<op_first> and C<op_last> where appropriate).
480
481 =item *
482
483 The macro C<OpSIBLING_set>, added in 5.21.2, has been removed. It didn't
484 manipulate C<op_moresib> and has been superseded by C<OpMORESIB_set> et
485 al.
486
487 =item *
488
489 The C<op_sibling_splice> function now accepts a null C<parent> argument
490 where the splicing doesn't affect the first or last ops in the sibling
491 chain, and thus where the parent doesn't need to be updated accordingly.
492
493 =back
494
495
496 =back
497
498 =head1 Selected Bug Fixes
499
500 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
501 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
502
503 [ List each fix as a =item entry ]
504
505 =over 4
506
507 =item *
508
509 C<pack("D", $x)> and C<pack("F", $x)> now zero the padding on x86 long
510 double builds.  GCC 4.8 and later, under some build options, would
511 either overwrite the zero-initialized padding, or bypass the
512 initialized buffer entirely.  This caused F<op/pack.t> to fail.  [perl
513 #123971]
514
515 =item *
516
517 Extending an array cloned from a parent thread could result in
518 "Modification of a read-only value attempted" errors when attempting
519 to modify the new elements. [perl #124127]
520
521 =item *
522
523 An assertion failure and subsequent crash with C<< *x=<y> >> has been fixed.
524 [perl #123790]
525
526 =item *
527
528 An optimization for state variable initialization introduced in Perl 5.21.6 has
529 been reverted because it was found to exacerbate some other existing buggy
530 behaviour. [perl #124160]
531
532 =item *
533
534 The extension of another optimization to cover more ops in Perl 5.21 has also
535 been reverted to its Perl 5.20 state as a temporary fix for regression issues
536 that it caused. [perl #123790]
537
538 =back
539
540 =head1 Known Problems
541
542 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
543 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
544 platform specific bugs also go here.
545
546 [ List each fix as a =item entry ]
547
548 =over 4
549
550 =item *
551
552 XXX
553
554 =back
555
556 =head1 Errata From Previous Releases
557
558 =over 4
559
560 =item *
561
562 XXX Add anything here that we forgot to add, or were mistaken about, in
563 the perldelta of a previous release.
564
565 =back
566
567 =head1 Obituary
568
569 XXX If any significant core contributor has died, we've added a short obituary
570 here.
571
572 =head1 Acknowledgements
573
574 XXX Generate this with:
575
576   perl Porting/acknowledgements.pl v5.21.10..HEAD
577
578 =head1 Reporting Bugs
579
580 If you find what you think is a bug, you might check the articles recently
581 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
582 https://rt.perl.org/ .  There may also be information at
583 http://www.perl.org/ , the Perl Home Page.
584
585 If you believe you have an unreported bug, please run the L<perlbug> program
586 included with your release.  Be sure to trim your bug down to a tiny but
587 sufficient test case.  Your bug report, along with the output of C<perl -V>,
588 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
589
590 If the bug you are reporting has security implications, which make it
591 inappropriate to send to a publicly archived mailing list, then please send it
592 to perl5-security-report@perl.org.  This points to a closed subscription
593 unarchived mailing list, which includes all the core committers, who will be
594 able to help assess the impact of issues, figure out a resolution, and help
595 co-ordinate the release of patches to mitigate or fix the problem across all
596 platforms on which Perl is supported.  Please only use this address for
597 security issues in the Perl core, not for modules independently distributed on
598 CPAN.
599
600 =head1 SEE ALSO
601
602 The F<Changes> file for an explanation of how to view exhaustive details on
603 what changed.
604
605 The F<INSTALL> file for how to build Perl.
606
607 The F<README> file for general stuff.
608
609 The F<Artistic> and F<Copying> files for copyright information.
610
611 =cut