This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta - Documentation and Diagnostics
[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.31.5
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.31.4 release and the 5.31.5
13 release.
14
15 If you are upgrading from an earlier release such as 5.31.3, first read
16 L<perl5314delta>, which describes differences between 5.31.3 and 5.31.4.
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 =head2 Modifiable variables are no longer permitted in constants
49
50 Code like:
51
52     my $var;
53     $sub = sub () { $var };
54
55 where C<$var> is referenced elsewhere in some sort of modiable context
56 now produces an exception when the sub is defined.
57
58 This error can be avoided by adding a return to the sub definition:
59
60     $sub = sub () { return $var };
61
62 This has been deprecated since perl 5.22.
63
64 [perl #131138]
65
66 =head1 Deprecations
67
68 XXX Any deprecated features, syntax, modules etc. should be listed here.
69
70 =head2 Module removals
71
72 XXX Remove this section if not applicable.
73
74 The following modules will be removed from the core distribution in a
75 future release, and will at that time need to be installed from CPAN.
76 Distributions on CPAN which require these modules will need to list them as
77 prerequisites.
78
79 The core versions of these modules will now issue C<"deprecated">-category
80 warnings to alert you to this fact.  To silence these deprecation warnings,
81 install the modules in question from CPAN.
82
83 Note that these are (with rare exceptions) fine modules that you are encouraged
84 to continue to use.  Their disinclusion from core primarily hinges on their
85 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
86 not usually on concerns over their design.
87
88 =over
89
90 =item XXX
91
92 XXX Note that deprecated modules should be listed here even if they are listed
93 as an updated module in the L</Modules and Pragmata> section.
94
95 =back
96
97 [ List each other deprecation as a =head2 entry ]
98
99 =head1 Performance Enhancements
100
101 XXX Changes which enhance performance without changing behaviour go here.
102 There may well be none in a stable release.
103
104 [ List each enhancement as an =item entry ]
105
106 =over 4
107
108 =item *
109
110 XXX
111
112 =back
113
114 =head1 Modules and Pragmata
115
116 =head2 Updated Modules and Pragmata
117
118 =over 4
119
120 =item *
121
122 L<B> has been upgraded from version 1.76 to 1.77.
123
124 =item *
125
126 L<B::Deparse> has been upgraded from version 1.49 to 1.50.
127
128 =item *
129
130 L<Devel::PPPort> has been upgraded from version 3.55 to 3.54.
131
132 =item *
133
134 L<Digest::MD5> has been upgraded from version 2.55 to 2.55_01.
135
136 =item *
137
138 L<Dumpvalue> has been upgraded from version 1.18 to 1.21.
139
140 Previously, when dumping elements of an array and encountering an undefined
141 value, the string printed would have been C<empty array>.  This has been
142 changed to what was apparently originally intended:  C<empty slot>.
143
144 =item *
145
146 L<ExtUtils::CBuilder> has been upgraded from version 0.280232 to 0.280233.
147
148 =item *
149
150 L<Math::BigInt> has been upgraded from version 1.999816 to 1.999817_01.
151
152 =item *
153
154 L<Math::BigInt::FastCalc> has been upgraded from version 0.5008 to 0.5009.
155
156 =item *
157
158 L<Module::CoreList> has been upgraded from version 5.20190920 to 5.20191020.
159
160 =item *
161
162 L<Safe> has been upgraded from version 2.40 to 2.41.
163
164 =item *
165
166 L<threads> has been upgraded from version 2.22 to 2.23.
167
168 =item *
169
170 L<Time::HiRes> has been upgraded from version 1.9763 to 1.9764.
171
172 =item *
173
174 L<XS::APItest> has been upgraded from version 1.03 to 1.04.
175
176 If there was something important to note about this change, include that here.
177
178 =back
179
180 =head1 Documentation
181
182 =head2 Changes to Existing Documentation
183
184 We have attempted to update the documentation to reflect the changes
185 listed in this document.  If you find any we have missed, send email
186 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
187
188 =head3 L<perlguts>
189
190 =over 4
191
192 =item *
193
194 Details of the various stacks within the perl interpreter are now explained
195 here.
196
197 =back
198
199 Additionally, the following selected changes have been made:
200
201 =head3 URLs have been changed to https://, stale links updated
202
203 =over 4
204
205 =item *
206
207 Where applicable, the URLs in the documentation have been moved from
208 using the http:// protocol to https:// . This also affects the location
209 of the bug tracker at L<https://rt.perl.org>.
210
211 =item *
212
213 Some links to OS/2 libraries, Address Sanitizer and other system tools
214 had gone stale. These have been updated with working links.
215
216 =item *
217
218 Some links to old mails on perl5-porters had gone stale. These have been
219 updated with working links.
220
221 =back
222
223 =head1 Diagnostics
224
225 The following additions or changes have been made to diagnostic output,
226 including warnings and fatal error messages.  For the complete list of
227 diagnostic messages, see L<perldiag>.
228
229 =head2 Changes to Existing Diagnostics
230
231 =over 4
232
233 =item *
234
235 L<Can't use global %s in %s|perldiag/"Can't use global %s in %s">
236
237 This error message has been slightly reformatted from the original C<Can't use
238 global %s in "%s">, and in particular misleading error messages like C<Can't
239 use global $_ in "my"> are now rendered as C<Can't use global $_ in subroutine
240 signature>.
241
242 =item *
243
244 L<Constants from lexical variables potentially modified elsewhere are no longer permitted|perldiag/"Constants from lexical variables potentially modified elsewhere are no longer permitted">
245
246 This error message replaces the former C<Constants from lexical variables
247 potentially modified elsewhere are deprecated. This will not be allowed in Perl
248 5.32> to reflect the fact that this previously deprecated usage has now been
249 transformed into an exception.  The message's classification has also been
250 updated from D (deprecated) to F (fatal).
251
252 =back
253
254 =head1 Utility Changes
255
256 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
257 Most of these are built within the directory F<utils>.
258
259 [ List utility changes as a =head2 entry for each utility and =item
260 entries for each change
261 Use L<XXX> with program names to get proper documentation linking. ]
262
263 =head2 L<XXX>
264
265 =over 4
266
267 =item *
268
269 XXX
270
271 =back
272
273 =head1 Configuration and Compilation
274
275 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
276 go here.  Any other changes to the Perl build process should be listed here.
277 However, any platform-specific changes should be listed in the
278 L</Platform Support> section, instead.
279
280 [ List changes as an =item entry ].
281
282 =over 4
283
284 =item *
285
286 Perl now no longer probes for C<d_u32align>, defaulting to C<define>
287 on all platforms.  This check was error prone when it was done, which
288 was on 32-bit platforms only.  [perl #133495]
289
290 =item *
291
292 Documentation and hints for building perl on Z/OS (native EBCDIC) have
293 been updated. Still work in progress.
294
295 =item *
296
297 New probe for malloc_usable_size
298
299 =back
300
301 =head1 Testing
302
303 XXX Any significant changes to the testing of a freshly built perl should be
304 listed here.  Changes which create B<new> files in F<t/> go here as do any
305 large changes to the testing harness (e.g. when parallel testing was added).
306 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
307 that they represent may be covered elsewhere.
308
309 XXX If there were no significant test changes, say this:
310
311 Tests were added and changed to reflect the other additions and changes
312 in this release.
313
314 XXX If instead there were significant changes, say this:
315
316 Tests were added and changed to reflect the other additions and
317 changes in this release.  Furthermore, these significant changes were
318 made:
319
320 [ List each test improvement as an =item entry ]
321
322 =over 4
323
324 =item *
325
326 XXX
327
328 =back
329
330 =head1 Platform Support
331
332 XXX Any changes to platform support should be listed in the sections below.
333
334 [ Within the sections, list each platform as an =item entry with specific
335 changes as paragraphs below it. ]
336
337 =head2 New Platforms
338
339 XXX List any platforms that this version of perl compiles on, that previous
340 versions did not.  These will either be enabled by new files in the F<hints/>
341 directories, or new subdirectories and F<README> files at the top level of the
342 source tree.
343
344 =over 4
345
346 =item XXX-some-platform
347
348 XXX
349
350 =back
351
352 =head2 Discontinued Platforms
353
354 XXX List any platforms that this version of perl no longer compiles on.
355
356 =over 4
357
358 =item XXX-some-platform
359
360 XXX
361
362 =back
363
364 =head2 Platform-Specific Notes
365
366 XXX List any changes for specific platforms.  This could include configuration
367 and compilation changes or changes in portability/compatibility.  However,
368 changes within modules for platforms should generally be listed in the
369 L</Modules and Pragmata> section.
370
371 =over 4
372
373 =item Windows
374
375 Support for building perl with Visual C++ 6.0 has now been removed.
376
377 =back
378
379 =head1 Internal Changes
380
381 XXX Changes which affect the interface available to C<XS> code go here.  Other
382 significant internal changes for future core maintainers should be noted as
383 well.
384
385 [ List each change as an =item entry ]
386
387 =over 4
388
389 =item *
390
391 Added the C<<PL_curstackinfo->si_cxsubix>> field. This records the stack
392 index of the most recently pushed sub/format/eval context.  It is set and
393 restored automatically by C<cx_pushsub()>, C<cx_popsub()> etc., but would
394 need to be manually managed if you do any unusual manipulation of the
395 context stack.
396
397 =item *
398
399 Various macros dealing with character type classification and changing
400 case where the input is encoded in UTF-8 now require an extra parameter
401 to prevent potential reads beyond the end of the buffer.  Use of these
402 has generated a deprecation warning since 5.26.  Details are in
403 L<perldeprecation/In XS code, use of various macros dealing with UTF-8.>
404
405 =back
406
407 =head1 Selected Bug Fixes
408
409 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
410 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
411
412 [ List each fix as an =item entry ]
413
414 =over 4
415
416 =item *
417
418 XXX
419
420 =back
421
422 =head1 Known Problems
423
424 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
425 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
426 platform specific bugs also go here.
427
428 [ List each fix as an =item entry ]
429
430 =over 4
431
432 =item *
433
434 XXX
435
436 =back
437
438 =head1 Errata From Previous Releases
439
440 =over 4
441
442 =item *
443
444 XXX Add anything here that we forgot to add, or were mistaken about, in
445 the perldelta of a previous release.
446
447 =back
448
449 =head1 Obituary
450
451 XXX If any significant core contributor or member of the CPAN community has
452 died, add a short obituary here.
453
454 =head1 Acknowledgements
455
456 XXX Generate this with:
457
458   perl Porting/acknowledgements.pl v5.31.4..HEAD
459
460 =head1 Reporting Bugs
461
462 If you find what you think is a bug, you might check the perl bug database
463 at L<https://rt.perl.org/>.  There may also be information at
464 L<https://www.perl.org/>, the Perl Home Page.
465
466 If you believe you have an unreported bug, please run the L<perlbug> program
467 included with your release.  Be sure to trim your bug down to a tiny but
468 sufficient test case.  Your bug report, along with the output of C<perl -V>,
469 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
470
471 If the bug you are reporting has security implications which make it
472 inappropriate to send to a publicly archived mailing list, then see
473 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
474 for details of how to report the issue.
475
476 =head1 Give Thanks
477
478 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
479 you can do so by running the C<perlthanks> program:
480
481     perlthanks
482
483 This will send an email to the Perl 5 Porters list with your show of thanks.
484
485 =head1 SEE ALSO
486
487 The F<Changes> file for an explanation of how to view exhaustive details on
488 what changed.
489
490 The F<INSTALL> file for how to build Perl.
491
492 The F<README> file for general stuff.
493
494 The F<Artistic> and F<Copying> files for copyright information.
495
496 =cut