This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta: begin a to-do list
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =for comment
4 Stuff that needs to be done still:
5 e82485c davem [MERGE] refactor pp_match(), pp_subst(), regexec()
6
7 =head1 NAME
8
9 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
10 to be processed before release. ]
11
12 perldelta - what is new for perl v5.19.3
13
14 =head1 DESCRIPTION
15
16 This document describes differences between the 5.19.2 release and the 5.19.3
17 release.
18
19 If you are upgrading from an earlier release such as 5.19.1, first read
20 L<perl5192delta>, which describes differences between 5.19.1 and 5.19.2.
21
22 =head1 Notice
23
24 XXX Any important notices here
25
26 =head1 Core Enhancements
27
28 XXX New core language features go here.  Summarize user-visible core language
29 enhancements.  Particularly prominent performance optimisations could go
30 here, but most should go in the L</Performance Enhancements> section.
31
32 [ List each enhancement as a =head2 entry ]
33
34 =head2 B<-F> now implies B<-a> and B<-a> implies B<-n>
35
36 Previously B<-F> without B<-a> was a no-op, and B<-a> without B<-n> or
37 B<-p> was a no-op, with this change, if you supply B<-F> then both
38 B<-a> and B<-n> are implied and if you supply B<-a> then B<-n> is implied.
39
40 You can still use B<-p> for its extra behaviour. [perl #116190]
41
42 =head1 Security
43
44 XXX Any security-related notices go here.  In particular, any security
45 vulnerabilities closed should be noted here rather than in the
46 L</Selected Bug Fixes> section.
47
48 [ List each security issue as a =head2 entry ]
49
50 =head1 Incompatible Changes
51
52 XXX For a release on a stable branch, this section aspires to be:
53
54     There are no changes intentionally incompatible with 5.XXX.XXX
55     If any exist, they are bugs, and we request that you submit a
56     report.  See L</Reporting Bugs> below.
57
58 [ List each incompatible change as a =head2 entry ]
59
60 =head1 Deprecations
61
62 XXX Any deprecated features, syntax, modules etc. should be listed here.
63
64 =head2 Module removals
65
66 XXX Remove this section if inapplicable.
67
68 The following modules will be removed from the core distribution in a
69 future release, and will at that time need to be installed from CPAN.
70 Distributions on CPAN which require these modules will need to list them as
71 prerequisites.
72
73 The core versions of these modules will now issue C<"deprecated">-category
74 warnings to alert you to this fact.  To silence these deprecation warnings,
75 install the modules in question from CPAN.
76
77 Note that these are (with rare exceptions) fine modules that you are encouraged
78 to continue to use.  Their disinclusion from core primarily hinges on their
79 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
80 not usually on concerns over their design.
81
82 =over
83
84 XXX Note that deprecated modules should be listed here even if they are listed
85 as an updated module in the L</Modules and Pragmata> section.
86
87 =back
88
89 [ List each other deprecation as a =head2 entry ]
90
91 =head1 Performance Enhancements
92
93 XXX Changes which enhance performance without changing behaviour go here.
94 There may well be none in a stable release.
95
96 [ List each enhancement as a =item entry ]
97
98 =over 4
99
100 =item *
101
102 XXX
103
104 =back
105
106 =head1 Modules and Pragmata
107
108 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
109 go here.  If Module::CoreList is updated, generate an initial draft of the
110 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
111 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
112 below.  A paragraph summary for important changes should then be added by hand.
113 In an ideal world, dual-life modules would have a F<Changes> file that could be
114 cribbed.
115
116 [ Within each section, list entries as a =item entry ]
117
118 =head2 New Modules and Pragmata
119
120 =over 4
121
122 =item *
123
124 XXX
125
126 =back
127
128 =head2 Updated Modules and Pragmata
129
130 =over 4
131
132 =item *
133
134 L<B> has been upgraded from version 1.44 to 1.45.
135
136 Calling the C<GV> method on C<B::CV> objects created from a lexical
137 sub would return nonsense, possibly crashing perl. C<GV> now returns
138 C<undef> for lexical subs. [perl #118525]
139
140 Added the C<NAME_HEK> method to return the name of a lexical sub.
141
142 =item *
143
144 L<bignum> has been upgraded from version 0.35 to 0.36.
145
146 L<bigrat> wasn't correctly updating an internal variable when C<use>d
147 with a C<lib> option.
148
149 L<Carp> has been upgraded from 1.30 to 1.31
150
151 L<Carp> now handles objects with string overloads. It also allows objects
152 to specify how they appear in the stack dump with a C<CARP_TRACE> method,
153 and also allows the user to specify their own formatter for objects without
154 C<CARP_TRACE> as well as other references. [perl #92446]
155
156 =item *
157
158 L<Compress::Raw::Bzip2> has been upgraded from 2.061 to 2.062.
159
160 =item *
161
162 L<Compress::Raw::Zlib> has been upgraded from 2.061 to 2.062.
163
164 =item *
165
166 L<Config::Perl::V> has been upgraded from version 0.18 to 0.19.
167
168 =item *
169
170 L<Data::Dumper> has been upgraded from version 2.147 to 2.148.
171
172 The compatbility of the XS implementation with the pure perl version
173 under C<Useqq> has been improved. [perl #118933]
174
175 =item *
176
177 L<Devel::Peek> has been upgraded from version 1.12 to 1.13.
178
179 The C<SvREFCNT_inc()> and C<SvREFCNT_dec()> functions have been
180 removed and C<SvREFCNT()> will now work on non-scalars. [perl #117793]
181
182 =item *
183
184 L<Exporter> has been upgraded from version 5.68 to 5.69.
185
186 L<Exporter> would ignore custom C<$SIG{__WARN__}> handlers in
187 C<Exporter::Heavy>. [perl #39739]
188
189 =item *
190
191 The IO-Compress module collection has been upgraded from 2.061 to 2.062.
192
193 =item *
194
195 L<IPC::Cmd> has been upgraded from version 0.82 to 0.84.
196
197 C<run_forked> has various fixes/improvements, L<Socket> is only used where
198 needed and a regression introduced in 0.78 has been fixed.
199
200 =item *
201
202 The libnet module collection has been upgraded from version 1.22 to 1.23.
203
204 =item *
205
206 L<List::Util> has been upgraded from version 1.27 to 1.30
207
208 L<List::Util> now includes C<pairgrep>, C<pairmap>, C<pairs>, C<pairkeys>,
209 C<pairvalues> and C<pairfirst> functions that operate on even-sized lists of
210 pairs.
211
212 =item *
213
214 L<parent> has been upgraded from version 0.225 to 0.226.
215
216 =item *
217
218 L<Socket> has been upgraded from version 2.010 to 2.011.
219
220 Handle FreeBSD (or other platforms) returning shorter AF_UNIX sockaddr
221 structures due to embedded sun_len. [cpan #86613]
222
223 =item *
224
225 L<Storable> has been upgraded from version 2.45 to 2.46.
226
227 Avoid creating temporary objects for STORABLE_attach when they aren't
228 required. [perl #118907]
229
230 =item *
231
232 L<Time::Piece> has been upgraded from version 1.21 to 1.22.
233
234 =back
235
236 =head2 Removed Modules and Pragmata
237
238 =over 4
239
240 =item *
241
242 XXX
243
244 =back
245
246 =head1 Documentation
247
248 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
249 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
250
251 =head2 New Documentation
252
253 XXX Changes which create B<new> files in F<pod/> go here.
254
255 =head3 L<XXX>
256
257 XXX Description of the purpose of the new file here
258
259 =head2 Changes to Existing Documentation
260
261 XXX Changes which significantly change existing files in F<pod/> go here.
262 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
263 section.
264
265 =head3 L<perlopentut>
266
267 =over 4
268
269 =item *
270
271 The C<open> tutorial has been completely rewriten by Tom Christiansen, and now
272 focuses on covering only the basics, rather than providing a comprehensive
273 reference to all things openable.  This rewrite came as the result of a
274 vigorous discussion on perl5-porters kicked off by a set of improvements
275 written by Alexander Hartmaier to the existing C<perlopentut>.  A "more than
276 you ever wanted to know about C<open>" document may follow in subsequent
277 versions of perl.
278
279 =back
280
281 =head1 Diagnostics
282
283 The following additions or changes have been made to diagnostic output,
284 including warnings and fatal error messages.  For the complete list of
285 diagnostic messages, see L<perldiag>.
286
287 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
288 include any changes in L<perldiag> that reconcile it to the C<C> code.
289
290 =head2 New Diagnostics
291
292 XXX Newly added diagnostic messages go under here, separated into New Errors
293 and New Warnings
294
295 =head3 New Errors
296
297 =over 4
298
299 =item *
300
301 XXX L<message|perldiag/"message">
302
303 =back
304
305 =head3 New Warnings
306
307 =over 4
308
309 =item *
310
311 XXX L<message|perldiag/"message">
312
313 =back
314
315 =head2 Changes to Existing Diagnostics
316
317 XXX Changes (i.e. rewording) of diagnostic messages go here
318
319 =over 4
320
321 =item *
322
323 XXX Describe change here
324
325 =back
326
327 =head1 Utility Changes
328
329 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
330 Most of these are built within the directories F<utils> and F<x2p>.
331
332 [ List utility changes as a =head3 entry for each utility and =item
333 entries for each change
334 Use L<XXX> with program names to get proper documentation linking. ]
335
336 =head3 L<XXX>
337
338 =over 4
339
340 =item *
341
342 XXX
343
344 =back
345
346 =head1 Configuration and Compilation
347
348 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
349 go here.  Any other changes to the Perl build process should be listed here.
350 However, any platform-specific changes should be listed in the
351 L</Platform Support> section, instead.
352
353 [ List changes as a =item entry ].
354
355 =over 4
356
357 =item *
358
359 XXX
360
361 =back
362
363 =head1 Testing
364
365 XXX Any significant changes to the testing of a freshly built perl should be
366 listed here.  Changes which create B<new> files in F<t/> go here as do any
367 large changes to the testing harness (e.g. when parallel testing was added).
368 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
369 that they represent may be covered elsewhere.
370
371 [ List each test improvement as a =item entry ]
372
373 =over 4
374
375 =item *
376
377 XXX
378
379 =back
380
381 =head1 Platform Support
382
383 XXX Any changes to platform support should be listed in the sections below.
384
385 [ Within the sections, list each platform as a =item entry with specific
386 changes as paragraphs below it. ]
387
388 =head2 New Platforms
389
390 XXX List any platforms that this version of perl compiles on, that previous
391 versions did not.  These will either be enabled by new files in the F<hints/>
392 directories, or new subdirectories and F<README> files at the top level of the
393 source tree.
394
395 =over 4
396
397 =item XXX-some-platform
398
399 XXX
400
401 =back
402
403 =head2 Discontinued Platforms
404
405 XXX List any platforms that this version of perl no longer compiles on.
406
407 =over 4
408
409 =item XXX-some-platform
410
411 XXX
412
413 =back
414
415 =head2 Platform-Specific Notes
416
417 XXX List any changes for specific platforms.  This could include configuration
418 and compilation changes or changes in portability/compatibility.  However,
419 changes within modules for platforms should generally be listed in the
420 L</Modules and Pragmata> section.
421
422 =over 4
423
424 =item XXX-some-platform
425
426 XXX
427
428 =back
429
430 =head1 Internal Changes
431
432 XXX Changes which affect the interface available to C<XS> code go here.  Other
433 significant internal changes for future core maintainers should be noted as
434 well.
435
436 [ List each change as a =item entry ]
437
438 =over 4
439
440 =item *
441
442 C<sv_pos_b2u_flags> has been added to the API.  It is similar to
443 C<sv_pos_b2u>, but supports long strings on 64-bit platforms.
444
445 =back
446
447 =head1 Selected Bug Fixes
448
449 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
450 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
451
452 [ List each fix as a =item entry ]
453
454 =over 4
455
456 =item *
457
458 Autovivifying a subroutine stub via C<\&$glob> started causing crashes in
459 Perl 5.18.0 if the $glob was merely a copy of a real glob, i.e., a scalar
460 that had had a glob assigned to it.  This has been fixed [perl #119051].
461
462 =item *
463
464 On 64-bit platforms C<pos> can now be set to a value higher than 2**31-1
465 [perl #72766].
466
467 =item *
468
469 Perl used to leak an implementation detail when it came to referencing the
470 return values of certain operators.  C<for ($a+$b) { warn \$_; warn \$_ }>
471 used to display two different memory addresses, because the C<\> operator
472 was copying the variable.  Under threaded builds, it would also happen for
473 constants (C<for(1) { ... }>).  This has been fixed [perl #21979, #78194,
474 #89188, #109746, #114838, #115388].
475
476 =item *
477
478 The range operator C<..> was returning the same modifiable scalars with
479 each call, unless it was the only thing in a C<foreach> loop header.  This
480 meant that changes to values within the list returned would be visible the
481 next time the operator was executed [perl #3105].
482
483 =item *
484
485 Constant folding and subroutine inlining no longer cause operations that
486 would normally return new modifiable scalars to return read-only values
487 instead.
488
489 =item *
490
491 Closures of the form C<sub () { $some_variable }> are no longer inlined,
492 causing changes to the variable to be ignored by callers of the subroutine
493 [perl #79908].
494
495 =item *
496
497 Return values of certain operators such as C<ref> would sometimes be shared
498 between recursive calls to the same subroutine, causing the inner call to
499 modify the value returned by C<ref> in the outer call.  This has been
500 fixed.
501
502 =item *
503
504 C<__PACKAGE__> and constants returning a package name or hash key are now
505 consistently read-only.  In various previous Perl releases, they have
506 become mutable under certain circumstances.
507
508 =back
509
510 =head1 Known Problems
511
512 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
513 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
514 platform specific bugs also go here.
515
516 [ List each fix as a =item entry ]
517
518 =over 4
519
520 =item *
521
522 XXX
523
524 =back
525
526 =head1 Obituary
527
528 XXX If any significant core contributor has died, we've added a short obituary
529 here.
530
531 =head1 Acknowledgements
532
533 XXX Generate this with:
534
535   perl Porting/acknowledgements.pl v5.19.2..HEAD
536
537 =head1 Reporting Bugs
538
539 If you find what you think is a bug, you might check the articles recently
540 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
541 http://rt.perl.org/perlbug/ .  There may also be information at
542 http://www.perl.org/ , the Perl Home Page.
543
544 If you believe you have an unreported bug, please run the L<perlbug> program
545 included with your release.  Be sure to trim your bug down to a tiny but
546 sufficient test case.  Your bug report, along with the output of C<perl -V>,
547 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
548
549 If the bug you are reporting has security implications, which make it
550 inappropriate to send to a publicly archived mailing list, then please send it
551 to perl5-security-report@perl.org.  This points to a closed subscription
552 unarchived mailing list, which includes all the core committers, who will be
553 able to help assess the impact of issues, figure out a resolution, and help
554 co-ordinate the release of patches to mitigate or fix the problem across all
555 platforms on which Perl is supported.  Please only use this address for
556 security issues in the Perl core, not for modules independently distributed on
557 CPAN.
558
559 =head1 SEE ALSO
560
561 The F<Changes> file for an explanation of how to view exhaustive details on
562 what changed.
563
564 The F<INSTALL> file for how to build Perl.
565
566 The F<README> file for general stuff.
567
568 The F<Artistic> and F<Copying> files for copyright information.
569
570 =cut