This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
49b2a7deadcd5617464d50fed0dccd57ce5bfe4f
[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.3
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.31.2 release and the 5.31.3
13 release.
14
15 If you are upgrading from an earlier release such as 5.31.1, first read
16 L<perl5312delta>, which describes differences between 5.31.1 and 5.31.2.
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 Plain "0" string now treated as a number for range operator
49
50 Previously a range C< "0" .. "-1" > would produce a range of numeric
51 strings from "0" through "99", this now produces an empty list, just
52 as C< 0 .. -1 > does.
53
54 This was due to a special case that treated strings starting with "0"
55 as strings so ranges like C< "00" .. "03" > produced C< "00", "01",
56 "02", "03" >, but didn't specially handle the string C<"0">.
57
58 [perl #133695]
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 not applicable.
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 =item XXX
85
86 XXX Note that deprecated modules should be listed here even if they are listed
87 as an updated module in the L</Modules and Pragmata> section.
88
89 =back
90
91 [ List each other deprecation as a =head2 entry ]
92
93 =head1 Performance Enhancements
94
95 XXX Changes which enhance performance without changing behaviour go here.
96 There may well be none in a stable release.
97
98 [ List each enhancement as an =item entry ]
99
100 =over 4
101
102 =item *
103
104 XXX
105
106 =back
107
108 =head1 Modules and Pragmata
109
110 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
111 go here.  If Module::CoreList is updated, generate an initial draft of the
112 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
113 for important changes should then be added by hand.  In an ideal world,
114 dual-life modules would have a F<Changes> file that could be cribbed.
115
116 The list of new and updated modules is modified automatically as part of
117 preparing a Perl release, so the only reason to manually add entries here is if
118 you're summarising the important changes in the module update. (Also, if the
119 manually-added details don't match the automatically-generated ones, the
120 release manager will have to investigate the situation carefully.)
121
122 [ Within each section, list entries as an =item entry ]
123
124 =head2 New Modules and Pragmata
125
126 =over 4
127
128 =item *
129
130 XXX Remove this section if not applicable.
131
132 =back
133
134 =head2 Updated Modules and Pragmata
135
136 =over 4
137
138 =item *
139
140 L<Devel::PPPort> has been upgraded from version 3.54 to 3.55.
141
142 The test files generated on Win32 are now identical to when they are
143 generated on POSIX-like systems.
144
145 =item *
146
147 L<File::Find> has been upgraded from version 1.36 to 1.37.
148
149 On Win32, the tests no longer require either a file in the drive root
150 directory, or a writable root directory.
151
152 =item *
153
154 L<Thread> has been upgraded from version 3.04 to 3.05.
155
156 =item *
157
158 L<XXX> has been upgraded from version A.xx to B.yy.
159
160 If there was something important to note about this change, include that here.
161
162 =back
163
164 =head2 Removed Modules and Pragmata
165
166 =over 4
167
168 =item *
169
170 XXX
171
172 =back
173
174 =head1 Documentation
175
176 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
177 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
178
179 =head2 New Documentation
180
181 XXX Changes which create B<new> files in F<pod/> go here.
182
183 =head3 L<XXX>
184
185 XXX Description of the purpose of the new file here
186
187 =head2 Changes to Existing Documentation
188
189 We have attempted to update the documentation to reflect the changes
190 listed in this document.  If you find any we have missed, send email
191 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
192
193 XXX Changes which significantly change existing files in F<pod/> go here.
194 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
195 section.
196
197 Additionally, the following selected changes have been made:
198
199 =head3 L<XXX>
200
201 =over 4
202
203 =item *
204
205 XXX Description of the change here
206
207 =back
208
209 =head1 Diagnostics
210
211 The following additions or changes have been made to diagnostic output,
212 including warnings and fatal error messages.  For the complete list of
213 diagnostic messages, see L<perldiag>.
214
215 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
216 include any changes in L<perldiag> that reconcile it to the C<C> code.
217
218 =head2 New Diagnostics
219
220 XXX Newly added diagnostic messages go under here, separated into New Errors
221 and New Warnings
222
223 =head3 New Errors
224
225 =over 4
226
227 =item *
228
229 XXX L<message|perldiag/"message">
230
231 =back
232
233 =head3 New Warnings
234
235 =over 4
236
237 =item *
238
239 XXX L<message|perldiag/"message">
240
241 =back
242
243 =head2 Changes to Existing Diagnostics
244
245 XXX Changes (i.e. rewording) of diagnostic messages go here
246
247 =over 4
248
249 =item *
250
251 XXX Describe change here
252
253 =back
254
255 =head1 Utility Changes
256
257 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
258 Most of these are built within the directory F<utils>.
259
260 [ List utility changes as a =head2 entry for each utility and =item
261 entries for each change
262 Use L<XXX> with program names to get proper documentation linking. ]
263
264 =head2 L<XXX>
265
266 =over 4
267
268 =item *
269
270 XXX
271
272 =back
273
274 =head1 Configuration and Compilation
275
276 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
277 go here.  Any other changes to the Perl build process should be listed here.
278 However, any platform-specific changes should be listed in the
279 L</Platform Support> section, instead.
280
281 [ List changes as an =item entry ].
282
283 =over 4
284
285 =item *
286
287 XXX
288
289 =back
290
291 =head1 Testing
292
293 XXX Any significant changes to the testing of a freshly built perl should be
294 listed here.  Changes which create B<new> files in F<t/> go here as do any
295 large changes to the testing harness (e.g. when parallel testing was added).
296 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
297 that they represent may be covered elsewhere.
298
299 XXX If there were no significant test changes, say this:
300
301 Tests were added and changed to reflect the other additions and changes
302 in this release.
303
304 XXX If instead there were significant changes, say this:
305
306 Tests were added and changed to reflect the other additions and
307 changes in this release.  Furthermore, these significant changes were
308 made:
309
310 [ List each test improvement as an =item entry ]
311
312 =over 4
313
314 =item *
315
316 XXX
317
318 =back
319
320 =head1 Platform Support
321
322 XXX Any changes to platform support should be listed in the sections below.
323
324 [ Within the sections, list each platform as an =item entry with specific
325 changes as paragraphs below it. ]
326
327 =head2 New Platforms
328
329 XXX List any platforms that this version of perl compiles on, that previous
330 versions did not.  These will either be enabled by new files in the F<hints/>
331 directories, or new subdirectories and F<README> files at the top level of the
332 source tree.
333
334 =over 4
335
336 =item XXX-some-platform
337
338 XXX
339
340 =back
341
342 =head2 Discontinued Platforms
343
344 XXX List any platforms that this version of perl no longer compiles on.
345
346 =over 4
347
348 =item XXX-some-platform
349
350 XXX
351
352 =back
353
354 =head2 Platform-Specific Notes
355
356 XXX List any changes for specific platforms.  This could include configuration
357 and compilation changes or changes in portability/compatibility.  However,
358 changes within modules for platforms should generally be listed in the
359 L</Modules and Pragmata> section.
360
361 =over 4
362
363 =item Windows
364
365 F<t/op/magic.t> could fail if environment varables starting with
366 C<FOO> already existed.
367
368 =back
369
370 =head1 Internal Changes
371
372 XXX Changes which affect the interface available to C<XS> code go here.  Other
373 significant internal changes for future core maintainers should be noted as
374 well.
375
376 [ List each change as an =item entry ]
377
378 =over 4
379
380 =item *
381
382 A new parser function L<parse_subsignature()|perlapi/parse_subsignature>
383 allows a keyword plugin to parse a subroutine signature while C<use feature
384 'signatures'> is in effect.  This allows custom keywords to implement
385 semantics similar to regular C<sub> declarations that include signatures.
386 [perl #132474]
387
388 =item *
389
390 Since on some platforms we need to hold a mutex when temporarily
391 switching locales, new macros (C<STORE_LC_NUMERIC_SET_TO_NEEDED_IN>,
392 C<WITH_LC_NUMERIC_SET_TO_NEEDED> and C<WITH_LC_NUMERIC_SET_TO_NEEDED_IN>)
393 have been added to make it easier to do this safely and efficiently
394 as part of [perl #134172].
395
396 =back
397
398 =head1 Selected Bug Fixes
399
400 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
401 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
402
403 [ List each fix as an =item entry ]
404
405 =over 4
406
407 =item *
408
409 C<< $@ = 100; die; >> now correctly propagates the 100 as an exception
410 instead of ignoring it.  [perl #134291]
411
412 =item *
413
414 C<< 0 0x@ >> no longer asserts in S_no_op().  [perl #134310]
415
416 =back
417
418 =head1 Known Problems
419
420 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
421 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
422 platform specific bugs also go here.
423
424 [ List each fix as an =item entry ]
425
426 =over 4
427
428 =item *
429
430 XXX
431
432 =back
433
434 =head1 Errata From Previous Releases
435
436 =over 4
437
438 =item *
439
440 XXX Add anything here that we forgot to add, or were mistaken about, in
441 the perldelta of a previous release.
442
443 =back
444
445 =head1 Obituary
446
447 XXX If any significant core contributor or member of the CPAN community has
448 died, add a short obituary here.
449
450 =head1 Acknowledgements
451
452 XXX Generate this with:
453
454   perl Porting/acknowledgements.pl v5.31.2..HEAD
455
456 =head1 Reporting Bugs
457
458 If you find what you think is a bug, you might check the perl bug database
459 at L<https://rt.perl.org/>.  There may also be information at
460 L<http://www.perl.org/>, the Perl Home Page.
461
462 If you believe you have an unreported bug, please run the L<perlbug> program
463 included with your release.  Be sure to trim your bug down to a tiny but
464 sufficient test case.  Your bug report, along with the output of C<perl -V>,
465 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
466
467 If the bug you are reporting has security implications which make it
468 inappropriate to send to a publicly archived mailing list, then see
469 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
470 for details of how to report the issue.
471
472 =head1 Give Thanks
473
474 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
475 you can do so by running the C<perlthanks> program:
476
477     perlthanks
478
479 This will send an email to the Perl 5 Porters list with your show of thanks.
480
481 =head1 SEE ALSO
482
483 The F<Changes> file for an explanation of how to view exhaustive details on
484 what changed.
485
486 The F<INSTALL> file for how to build Perl.
487
488 The F<README> file for general stuff.
489
490 The F<Artistic> and F<Copying> files for copyright information.
491
492 =cut