This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
d43fd1c3628edd74529d3c7d42404254e90f29fc
[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
6 XXX needs to be processed before release. ]
7
8 perldelta - what is new for perl v5.17.0
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.16.0 release and
13 the 5.17.0 release.
14
15 If you are upgrading from an earlier release such as 5.16.0, first read
16 L<perl5160delta>, which describes differences between 5.15.0 and
17 5.16.0.
18
19 =head1 Notice
20
21 XXX Any important notices here
22
23 =head1 Core Enhancements
24
25 XXX New core language features go here. Summarise user-visible core language
26 enhancements. Particularly prominent performance optimisations could go
27 here, but most should go in the L</Performance Enhancements> section.
28
29 [ List each enhancement as a =head2 entry ]
30
31 =head1 Security
32
33 XXX Any security-related notices go here.  In particular, any security
34 vulnerabilities closed should be noted here rather than in the
35 L</Selected Bug Fixes> section.
36
37 [ List each security issue as a =head2 entry ]
38
39 =head1 Incompatible Changes
40
41 XXX For a release on a stable branch, this section aspires to be:
42
43     There are no changes intentionally incompatible with 5.XXX.XXX
44     If any exist, they are bugs, and we request that you submit a
45     report.  See L</Reporting Bugs> below.
46
47 [ List each incompatible change as a =head2 entry ]
48
49 =head1 Deprecations
50
51 XXX Any deprecated features, syntax, modules etc. should be listed here.
52 In particular, deprecated modules should be listed here even if they are
53 listed as an updated module in the L</Modules and Pragmata> section.
54
55 [ List each deprecation as a =head2 entry ]
56
57 =head1 Performance Enhancements
58
59 XXX Changes which enhance performance without changing behaviour go here. There
60 may well be none in a stable release.
61
62 [ List each enhancement as a =item entry ]
63
64 =over 4
65
66 =item *
67
68 XXX
69
70 =back
71
72 =head1 Modules and Pragmata
73
74 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
75 go here.  If Module::CoreList is updated, generate an initial draft of the
76 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
77 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
78 below.  A paragraph summary for important changes should then be added by hand.
79 In an ideal world, dual-life modules would have a F<Changes> file that could be
80 cribbed.
81
82 [ Within each section, list entries as a =item entry ]
83
84 =head2 New Modules and Pragmata
85
86 =over 4
87
88 =item *
89
90 XXX
91
92 =back
93
94 =head2 Updated Modules and Pragmata
95
96 =over 4
97
98 =item *
99
100 L<File::stat> has been upgraded from version 1.05 to 1.06.
101
102 C<File::stat> ignores the L<filetest> pragma, and warns when used in
103 combination therewith.  But it was not warning for C<-r>.  This has been
104 fixed [perl #111640].
105
106 C<-p> now works, and does not return false for pipes [perl #111638].
107
108 =item *
109
110 L<Hash::Util> has been upgraded from version 0.11 to 0.12.
111
112 C<hash_unlocked> and C<hashref_unlocked> now returns true if the hash is
113 unlocked, instead of always returning false [perl #112126].
114
115 C<hash_unlocked>, C<hashref_unlocked>, C<lock_hash_recurse> and
116 C<unlock_hash_recurse> are now exportable [perl #112126].
117
118 Two new functions, C<hash_locked> and C<hashref_locked>, have been added.
119 Oddly enough, these two functions were already exported, even though they
120 did not exist [perl #112126].
121
122 =item *
123
124 L<Storable> has been upgraded from version 2.34 to 2.35.
125
126 Modifying C<$_[0]> within C<STORABLE_freeze> no longer results in crashes
127 [perl #112358].
128
129 =back
130
131 =head2 Removed Modules and Pragmata
132
133 =over 4
134
135 =item *
136
137 XXX
138
139 =back
140
141 =head1 Documentation
142
143 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
144 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
145
146 =head2 New Documentation
147
148 XXX Changes which create B<new> files in F<pod/> go here.
149
150 =head3 L<XXX>
151
152 XXX Description of the purpose of the new file here
153
154 =head2 Changes to Existing Documentation
155
156 XXX Changes which significantly change existing files in F<pod/> go here.
157 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
158 section.
159
160 =head3 L<XXX>
161
162 =over 4
163
164 =item *
165
166 XXX Description of the change here
167
168 =back
169
170 =head1 Diagnostics
171
172 The following additions or changes have been made to diagnostic output,
173 including warnings and fatal error messages.  For the complete list of
174 diagnostic messages, see L<perldiag>.
175
176 XXX New or changed warnings emitted by the core's C<C> code go here. Also
177 include any changes in L<perldiag> that reconcile it to the C<C> code.
178
179 [ Within each section, list entries as a =item entry that links to perldiag,
180   e.g.
181
182   =item *
183
184   L<Invalid version object|perldiag/"Invalid version object">
185 ]
186
187 =head2 New Diagnostics
188
189 XXX Newly added diagnostic messages go here
190
191 =head3 New Errors
192
193 =over 4
194
195 =item *
196
197 XXX L<message|perldiag/"message">
198
199 =back
200
201 =head3 New Warnings
202
203 =over 4
204
205 =item *
206
207 XXX L<message|perldiag/"message">
208
209 =back
210
211 =head2 Changes to Existing Diagnostics
212
213 XXX Changes (i.e. rewording) of diagnostic messages go here
214
215 =over 4
216
217 =item *
218
219 XXX Describe change here
220
221 =back
222
223 =head1 Utility Changes
224
225 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
226 here. Most of these are built within the directories F<utils> and F<x2p>.
227
228 [ List utility changes as a =head3 entry for each utility and =item
229 entries for each change
230 Use L<XXX> with program names to get proper documentation linking. ]
231
232 =head3 L<XXX>
233
234 =over 4
235
236 =item *
237
238 XXX
239
240 =back
241
242 =head1 Configuration and Compilation
243
244 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
245 go here.  Any other changes to the Perl build process should be listed here.
246 However, any platform-specific changes should be listed in the
247 L</Platform Support> section, instead.
248
249 [ List changes as a =item entry ].
250
251 =over 4
252
253 =item *
254
255 XXX
256
257 =back
258
259 =head1 Testing
260
261 XXX Any significant changes to the testing of a freshly built perl should be
262 listed here.  Changes which create B<new> files in F<t/> go here as do any
263 large changes to the testing harness (e.g. when parallel testing was added).
264 Changes to existing files in F<t/> aren't worth summarising, although the bugs
265 that they represent may be covered elsewhere.
266
267 [ List each test improvement as a =item entry ]
268
269 =over 4
270
271 =item *
272
273 XXX
274
275 =back
276
277 =head1 Platform Support
278
279 XXX 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
282 changes as paragraphs below it. ]
283
284 =head2 New Platforms
285
286 XXX List any platforms that this version of perl compiles on, that previous
287 versions did not. These will either be enabled by new files in the F<hints/>
288 directories, or new subdirectories and F<README> files at the top level of the
289 source tree.
290
291 =over 4
292
293 =item XXX-some-platform
294
295 XXX
296
297 =back
298
299 =head2 Discontinued Platforms
300
301 XXX List any platforms that this version of perl no longer compiles on.
302
303 =over 4
304
305 =item XXX-some-platform
306
307 XXX
308
309 =back
310
311 =head2 Platform-Specific Notes
312
313 XXX List any changes for specific platforms. This could include configuration
314 and compilation changes or changes in portability/compatibility.  However,
315 changes within modules for platforms should generally be listed in the
316 L</Modules and Pragmata> section.
317
318 =over 4
319
320 =item XXX-some-platform
321
322 XXX
323
324 =back
325
326 =head1 Internal Changes
327
328 XXX Changes which affect the interface available to C<XS> code go here.
329 Other significant internal changes for future core maintainers should
330 be noted as well.
331
332 [ List each change as a =item entry ]
333
334 =over 4
335
336 =item *
337
338 The C<SVf_AMAGIC> flag to indicate overloading is now on the stash, not the
339 object.  It is now set automatically whenever a method or @ISA changes, so
340 its meaning has changed, too.  It now means "potentially overloaded".  When
341 the overload table is calculated, the flag is automatically turned off if
342 there is no overloading, so there should be no noticeable slowdown.
343
344 The staleness of the overload tables is now checked when overload methods
345 are invoked, rather than during C<bless>.
346
347 "A" magic is gone.  The changes to the handling of the C<SVf_AMAGIC> flag
348 eliminate the need for it.
349
350 The core no longer increments C<PL_amagic_generation> (it doesn't need to).
351 But an XS module can still increment it to mark all overload tables as
352 stale.  (It is still not part of the API, though.)  Do not rely on this.
353 It may be deleted in the next release.
354
355 The fallback overload setting is now stored in its own stash entry, called
356 "(fallback".
357
358 =back
359
360 =head1 Selected Bug Fixes
361
362 XXX Important bug fixes in the core language are summarised here.
363 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
364 L</Modules and Pragmata>.
365
366 [ List each fix as a =item entry ]
367
368 =over 4
369
370 =item *
371
372 C<goto ''> now looks for an empty label, producing the "goto must have
373 label" error message, instead of exiting the program [perl #111794].
374
375 =item *
376
377 C<goto "\0"> now dies with "Can't find label" instead of "goto must have
378 label".
379
380 =item *
381
382 The C function C<hv_store> used to result in crashes when used on C<%^H>
383 [perl #111000].
384
385 =item *
386
387 A call checker attached to a closure prototype via C<cv_set_call_checker>
388 is now copied to closures cloned from it.  So C<cv_set_call_checker> now
389 works inside an attribute handler for a closure.
390
391 =item *
392
393 Writing to C<$^N> used to have no effect.  Now it croaks with "Modification
394 of a read-only value" by default, but that can be overridden by a custom
395 regular expression engine, as with C<$1> [perl #112184].
396
397 =item *
398
399 C<undef> on a control character glob (C<undef *^H>) no longer emits an
400 erroneous warning about ambiguity [perl #112456].
401
402 =item *
403
404 For efficiency's sake, many operators and built-in functions return the
405 same scalar each time.  Lvalue subroutines and subroutines in the CORE::
406 namespace were allowing this implementation detail to leak through.
407 C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB".  The same thing
408 would happen with an lvalue subroutine returning the return value of C<uc>.
409 Now the value is copied in such cases.
410
411 =item *
412
413 C<method {}> syntax with an empty block or a block returning an empty list
414 used to crash or use some random value left on the stack as its invocant.
415 Now it produces an error.
416
417 =item *
418
419 C<vec> now works with extremely large offsets (>2 GB) [perl #111730].
420
421 =item *
422
423 Changes to overload settings now take effect immediately, as do changes to
424 inheritance that affect overloading.  They used to take effect only after
425 C<bless>.
426
427 Objects that were created before a class had any overloading used to remain
428 non-overloaded even if the class gained overloading through C<use overload>
429 or @ISA changes, and even after C<bless>.  This has been fixed
430 [perl #112708].
431
432 =item *
433
434 Classes with overloading can now inherit fallback values.
435
436 =back
437
438 =head1 Known Problems
439
440 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
441 tests that had to be C<TODO>ed for the release would be noted here, unless
442 they were specific to a particular platform (see below).
443
444 This is a list of some significant unfixed bugs, which are regressions
445 from either 5.XXX.XXX or 5.XXX.XXX.
446
447 [ List each fix as a =item entry ]
448
449 =over 4
450
451 =item *
452
453 XXX
454
455 =back
456
457 =head1 Obituary
458
459 XXX If any significant core contributor has died, we've added a short obituary
460 here.
461
462 =head1 Acknowledgements
463
464 XXX Generate this with:
465
466   perl Porting/acknowledgements.pl v5.16.0..HEAD
467
468 =head1 Reporting Bugs
469
470 If you find what you think is a bug, you might check the articles
471 recently posted to the comp.lang.perl.misc newsgroup and the perl
472 bug database at http://rt.perl.org/perlbug/ .  There may also be
473 information at http://www.perl.org/ , the Perl Home Page.
474
475 If you believe you have an unreported bug, please run the L<perlbug>
476 program included with your release.  Be sure to trim your bug down
477 to a tiny but sufficient test case.  Your bug report, along with the
478 output of C<perl -V>, will be sent off to perlbug@perl.org to be
479 analysed by the Perl porting team.
480
481 If the bug you are reporting has security implications, which make it
482 inappropriate to send to a publicly archived mailing list, then please send
483 it to perl5-security-report@perl.org. This points to a closed subscription
484 unarchived mailing list, which includes
485 all the core committers, who will be able
486 to help assess the impact of issues, figure out a resolution, and help
487 co-ordinate the release of patches to mitigate or fix the problem across all
488 platforms on which Perl is supported. Please only use this address for
489 security issues in the Perl core, not for modules independently
490 distributed on CPAN.
491
492 =head1 SEE ALSO
493
494 The F<Changes> file for an explanation of how to view exhaustive details
495 on what changed.
496
497 The F<INSTALL> file for how to build Perl.
498
499 The F<README> file for general stuff.
500
501 The F<Artistic> and F<Copying> files for copyright information.
502
503 =cut