This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
RMG tweaks
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
4234ac96
AC
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.29.5
e4c43fa1 9
4026b091
S
10=head1 DESCRIPTION
11
4234ac96 12This document describes differences between the 5.29.4 release and the 5.29.5
4026b091
S
13release.
14
4234ac96
AC
15If you are upgrading from an earlier release such as 5.29.3, first read
16L<perl5294delta>, which describes differences between 5.29.3 and 5.29.4.
17
18=head1 Notice
19
20XXX Any important notices here
7a54f67e 21
21d34e95
JSA
22=head1 Core Enhancements
23
4234ac96
AC
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
27
28[ List each enhancement as a =head2 entry ]
4288c5b9 29
dafb2544
KW
30=head2 C<-Drv> now means something on C<-DDEBUGGING> builds
31
32Now, adding the verbose flag (C<-Dv>) to the C<-Dr> flag turns on all
33possible regular expression debugging.
34
4234ac96
AC
35=head1 Security
36
37XXX Any security-related notices go here. In particular, any security
38vulnerabilities closed should be noted here rather than in the
39L</Selected Bug Fixes> section.
40
41[ List each security issue as a =head2 entry ]
4288c5b9 42
21d34e95
JSA
43=head1 Incompatible Changes
44
4234ac96 45XXX For a release on a stable branch, this section aspires to be:
c22e17d0 46
4234ac96
AC
47 There are no changes intentionally incompatible with 5.XXX.XXX
48 If any exist, they are bugs, and we request that you submit a
49 report. See L</Reporting Bugs> below.
c22e17d0 50
4234ac96 51[ List each incompatible change as a =head2 entry ]
2ba232eb 52
4234ac96 53=head1 Deprecations
2ba232eb 54
4234ac96 55XXX Any deprecated features, syntax, modules etc. should be listed here.
2ba232eb 56
4234ac96 57=head2 Module removals
2ba232eb 58
4234ac96 59XXX Remove this section if not applicable.
2ba232eb 60
4234ac96
AC
61The following modules will be removed from the core distribution in a
62future release, and will at that time need to be installed from CPAN.
63Distributions on CPAN which require these modules will need to list them as
64prerequisites.
2ba232eb 65
4234ac96
AC
66The core versions of these modules will now issue C<"deprecated">-category
67warnings to alert you to this fact. To silence these deprecation warnings,
68install the modules in question from CPAN.
69
70Note that these are (with rare exceptions) fine modules that you are encouraged
71to continue to use. Their disinclusion from core primarily hinges on their
72necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
73not usually on concerns over their design.
74
75=over
2ba232eb 76
4234ac96
AC
77=item XXX
78
79XXX Note that deprecated modules should be listed here even if they are listed
80as an updated module in the L</Modules and Pragmata> section.
2ba232eb
TC
81
82=back
83
4234ac96
AC
84[ List each other deprecation as a =head2 entry ]
85
86=head1 Performance Enhancements
87
88XXX Changes which enhance performance without changing behaviour go here.
89There may well be none in a stable release.
90
91[ List each enhancement as an =item entry ]
2ba232eb 92
4234ac96 93=over 4
747c94ed 94
4234ac96 95=item *
747c94ed 96
3db0bccc
KW
97Regular expression pattern matching of things like C<qr/[^I<a>]/> is
98significantly sped up, where I<a> is any ASCII character. Which classes
99will get this speed up is complicated and depends on the underlying bit
100patterns of those characters, so differs between ASCII and EBCDIC
101platforms, but all case pairs, like C<qr/[Gg]/> are included, as is
102C<[^01]>.
747c94ed 103
4234ac96 104=back
747c94ed 105
4234ac96 106=head1 Modules and Pragmata
747c94ed 107
4234ac96
AC
108XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
109go here. If Module::CoreList is updated, generate an initial draft of the
110following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
111for important changes should then be added by hand. In an ideal world,
112dual-life modules would have a F<Changes> file that could be cribbed.
747c94ed 113
4234ac96
AC
114The list of new and updated modules is modified automatically as part of
115preparing a Perl release, so the only reason to manually add entries here is if
116you're summarising the important changes in the module update. (Also, if the
117manually-added details don't match the automatically-generated ones, the
118release manager will have to investigate the situation carefully.)
747c94ed 119
4234ac96 120[ Within each section, list entries as an =item entry ]
747c94ed 121
4234ac96 122=head2 New Modules and Pragmata
747c94ed 123
4234ac96 124=over 4
747c94ed 125
4234ac96 126=item *
747c94ed 127
4234ac96 128XXX Remove this section if not applicable.
747c94ed 129
4234ac96 130=back
7a54f67e 131
21d34e95 132=head2 Updated Modules and Pragmata
295a484e 133
21d34e95 134=over 4
928a385c
KE
135
136=item *
137
4234ac96 138L<XXX> has been upgraded from version A.xx to B.yy.
1060c83c 139
4234ac96 140If there was something important to note about this change, include that here.
1060c83c 141
4234ac96 142=back
65104f4c 143
4234ac96 144=head2 Removed Modules and Pragmata
65104f4c 145
4234ac96 146=over 4
21d34e95
JSA
147
148=item *
149
4234ac96 150XXX
21d34e95 151
4234ac96 152=back
21d34e95 153
4234ac96 154=head1 Documentation
21d34e95 155
4234ac96
AC
156XXX Changes to files in F<pod/> go here. Consider grouping entries by
157file and be sure to link to the appropriate page, e.g. L<perlfunc>.
21d34e95 158
4234ac96 159=head2 New Documentation
b0a362a2 160
4234ac96
AC
161XXX Changes which create B<new> files in F<pod/> go here.
162
163=head3 L<XXX>
164
165XXX Description of the purpose of the new file here
166
167=head2 Changes to Existing Documentation
168
169We have attempted to update the documentation to reflect the changes
170listed in this document. If you find any we have missed, send email
171to L<perlbug@perl.org|mailto:perlbug@perl.org>.
172
173XXX Changes which significantly change existing files in F<pod/> go here.
174However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
175section.
176
177Additionally, the following selected changes have been made:
178
179=head3 L<XXX>
b0a362a2 180
4234ac96 181=over 4
21d34e95
JSA
182
183=item *
184
4234ac96
AC
185XXX Description of the change here
186
187=back
188
189=head1 Diagnostics
190
191The following additions or changes have been made to diagnostic output,
192including warnings and fatal error messages. For the complete list of
193diagnostic messages, see L<perldiag>.
194
195XXX New or changed warnings emitted by the core's C<C> code go here. Also
196include any changes in L<perldiag> that reconcile it to the C<C> code.
197
198=head2 New Diagnostics
199
200XXX Newly added diagnostic messages go under here, separated into New Errors
201and New Warnings
202
203=head3 New Errors
204
205=over 4
21d34e95
JSA
206
207=item *
208
4234ac96
AC
209XXX L<message|perldiag/"message">
210
211=back
212
213=head3 New Warnings
214
215=over 4
21d34e95
JSA
216
217=item *
218
4234ac96
AC
219XXX L<message|perldiag/"message">
220
221=back
222
223=head2 Changes to Existing Diagnostics
224
225XXX Changes (i.e. rewording) of diagnostic messages go here
226
227=over 4
21d34e95 228
8de8eb77 229=item *
21d34e95 230
4234ac96
AC
231XXX Describe change here
232
233=back
234
235=head1 Utility Changes
236
237XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
238Most of these are built within the directory F<utils>.
239
240[ List utility changes as a =head2 entry for each utility and =item
241entries for each change
242Use L<XXX> with program names to get proper documentation linking. ]
243
244=head2 L<XXX>
245
246=over 4
21d34e95 247
8de8eb77 248=item *
21d34e95 249
4234ac96
AC
250XXX
251
252=back
253
254=head1 Configuration and Compilation
255
256XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
257go here. Any other changes to the Perl build process should be listed here.
258However, any platform-specific changes should be listed in the
259L</Platform Support> section, instead.
260
261[ List changes as an =item entry ].
262
263=over 4
21d34e95 264
8de8eb77 265=item *
21d34e95 266
e1895adc
KW
267Normally the thread-safe functions used only on threaded builds.
268It is now possible to force their use on unthreaded builds on systems
269that have them available, by including the
270C<-Accflags='-DUSE_THREAD_SAFE_LOCALE'> option to F<Configure>.
4234ac96
AC
271
272=back
273
274=head1 Testing
275
276XXX Any significant changes to the testing of a freshly built perl should be
277listed here. Changes which create B<new> files in F<t/> go here as do any
278large changes to the testing harness (e.g. when parallel testing was added).
279Changes to existing files in F<t/> aren't worth summarizing, although the bugs
280that they represent may be covered elsewhere.
281
282XXX If there were no significant test changes, say this:
283
284Tests were added and changed to reflect the other additions and changes
285in this release.
286
287XXX If instead there were significant changes, say this:
288
289Tests were added and changed to reflect the other additions and
290changes in this release. Furthermore, these significant changes were
291made:
292
293[ List each test improvement as an =item entry ]
294
295=over 4
21d34e95 296
8de8eb77 297=item *
21d34e95 298
4234ac96
AC
299XXX
300
301=back
302
303=head1 Platform Support
304
305XXX Any changes to platform support should be listed in the sections below.
306
307[ Within the sections, list each platform as an =item entry with specific
308changes as paragraphs below it. ]
309
310=head2 New Platforms
21d34e95 311
4234ac96
AC
312XXX List any platforms that this version of perl compiles on, that previous
313versions did not. These will either be enabled by new files in the F<hints/>
314directories, or new subdirectories and F<README> files at the top level of the
315source tree.
316
317=over 4
318
319=item XXX-some-platform
320
321XXX
21d34e95
JSA
322
323=back
324
4234ac96
AC
325=head2 Discontinued Platforms
326
327XXX List any platforms that this version of perl no longer compiles on.
21d34e95 328
373fec1e
SH
329=over 4
330
4234ac96
AC
331=item XXX-some-platform
332
333XXX
373fec1e 334
4234ac96
AC
335=back
336
337=head2 Platform-Specific Notes
338
339XXX List any changes for specific platforms. This could include configuration
340and compilation changes or changes in portability/compatibility. However,
341changes within modules for platforms should generally be listed in the
342L</Modules and Pragmata> section.
343
344=over 4
345
61911ec2 346=item Mac OS X
4234ac96 347
61911ec2
TC
348Perl's build and testing process on Mac OS X for C<-Duseshrplib>
349builds is now compatible with Mac OS X System Integrity Protection
350(SIP).
351
352SIP prevents binaries in F</bin> (and a few other places) being passed
353the C<DYLD_LIBRARY_PATH> environment variable. For our purposes this
354prevents C<DYLD_LIBRARY_PATH> from being passed to the shell, which
355prevents that variable being passed to the testing or build process,
356so running C<perl> couldn't find F<libperl.dylib>.
357
358To workaround that, the initial build of the F<perl> executable
359expects to find F<libperl.dylib> in the build directory, and the
360library path is then adjusted during installation to point to the
361installed library.
362
363[perl #126706]
21d34e95
JSA
364
365=back
366
367=head1 Internal Changes
368
4234ac96
AC
369XXX Changes which affect the interface available to C<XS> code go here. Other
370significant internal changes for future core maintainers should be noted as
371well.
372
373[ List each change as an =item entry ]
374
21d34e95
JSA
375=over 4
376
377=item *
378
4234ac96 379XXX
7a54f67e
CBW
380
381=back
382
7a54f67e
CBW
383=head1 Selected Bug Fixes
384
4234ac96
AC
385XXX Important bug fixes in the core language are summarized here. Bug fixes in
386files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
387
388[ List each fix as an =item entry ]
389
7a54f67e
CBW
390=over 4
391
392=item *
393
46d9f890
TC
394L<SDBM_File> is now more robust with corrupt database files. The
395improvements do not make SDBM files suitable as an interchange format.
396[perl #132147]
21d34e95 397
10056dd2
TC
398=item *
399
400C<binmode($fh);> or C<binmode($fh, ':raw');> now properly removes the
401C<:utf8> flag from the default C<:crlf> I/O layer on Win32. [perl
402#133604]
403
ea89b333
DM
404=item *
405
406The experimental reference aliasing feature was misinterpreting array and
407hash slice assignment as being localised, e.g.
408
409 \(@a[3,5,7]) = \(....);
410
411was being interpreted as:
412
413 local \(@a[3,5,7]) = \(....);
414
415[perl #133538]
416
417
4234ac96 418=back
fa126b81 419
4234ac96 420=head1 Known Problems
fa126b81 421
4234ac96
AC
422XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
423tests that had to be C<TODO>ed for the release would be noted here. Unfixed
424platform specific bugs also go here.
21d34e95 425
4234ac96
AC
426[ List each fix as an =item entry ]
427
428=over 4
7a54f67e 429
1060c83c
S
430=item *
431
4234ac96 432XXX
373fec1e
SH
433
434=back
435
4234ac96 436=head1 Errata From Previous Releases
7a54f67e 437
4234ac96 438=over 4
373fec1e 439
4234ac96 440=item *
21d34e95 441
4234ac96
AC
442XXX Add anything here that we forgot to add, or were mistaken about, in
443the perldelta of a previous release.
7a54f67e 444
4234ac96 445=back
21d34e95 446
4234ac96
AC
447=head1 Obituary
448
449XXX If any significant core contributor or member of the CPAN community has
450died, add a short obituary here.
451
452=head1 Acknowledgements
c4070876 453
4234ac96 454XXX Generate this with:
c4070876 455
4234ac96 456 perl Porting/acknowledgements.pl v5.29.4..HEAD
f5b73711 457
44691e6f
AB
458=head1 Reporting Bugs
459
373fec1e
SH
460If you find what you think is a bug, you might check the perl bug database
461at L<https://rt.perl.org/> . There may also be information at
b5cbfe35 462L<http://www.perl.org/> , the Perl Home Page.
44691e6f 463
e08634c5
SH
464If you believe you have an unreported bug, please run the L<perlbug> program
465included with your release. Be sure to trim your bug down to a tiny but
466sufficient test case. Your bug report, along with the output of C<perl -V>,
b5cbfe35 467will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 468
87c118b9
DM
469If the bug you are reporting has security implications which make it
470inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
471L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
472for details of how to report the issue.
44691e6f 473
390ae6f9
S
474=head1 Give Thanks
475
373fec1e
SH
476If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
477you can do so by running the C<perlthanks> program:
390ae6f9
S
478
479 perlthanks
480
481This will send an email to the Perl 5 Porters list with your show of thanks.
482
44691e6f
AB
483=head1 SEE ALSO
484
e08634c5
SH
485The F<Changes> file for an explanation of how to view exhaustive details on
486what changed.
44691e6f
AB
487
488The F<INSTALL> file for how to build Perl.
489
490The F<README> file for general stuff.
491
492The F<Artistic> and F<Copying> files for copyright information.
493
494=cut