This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
test $swap arg for smartmatch overload
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
25219f3f
KE
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.27.7
89853d76 9
b5cbfe35 10=head1 DESCRIPTION
89853d76 11
25219f3f 12This document describes differences between the 5.27.6 release and the 5.27.7
b5cbfe35 13release.
89853d76 14
25219f3f
KE
15If you are upgrading from an earlier release such as 5.27.5, first read
16L<perl5276delta>, which describes differences between 5.27.5 and 5.27.6.
e6a2e5ca 17
25219f3f 18=head1 Notice
e6a2e5ca 19
25219f3f 20XXX Any important notices here
f99042c8 21
25219f3f 22=head1 Core Enhancements
f99042c8 23
25219f3f
KE
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.
2e8ea15a 27
25219f3f 28[ List each enhancement as a =head2 entry ]
2e8ea15a 29
25219f3f 30=head1 Security
e6a2e5ca 31
25219f3f
KE
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
29d69c3c 35
25219f3f 36[ List each security issue as a =head2 entry ]
29d69c3c 37
25219f3f 38=head1 Incompatible Changes
29d69c3c 39
25219f3f 40XXX For a release on a stable branch, this section aspires to be:
29d69c3c 41
25219f3f
KE
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.
7d65f652 45
25219f3f 46[ List each incompatible change as a =head2 entry ]
7d65f652 47
25219f3f 48=head1 Deprecations
7d65f652 49
25219f3f 50XXX Any deprecated features, syntax, modules etc. should be listed here.
7d65f652 51
25219f3f 52=head2 Module removals
4c46c124 53
25219f3f 54XXX Remove this section if not applicable.
7d65f652 55
25219f3f
KE
56The following modules will be removed from the core distribution in a
57future release, and will at that time need to be installed from CPAN.
58Distributions on CPAN which require these modules will need to list them as
59prerequisites.
e2091bb6 60
25219f3f
KE
61The core versions of these modules will now issue C<"deprecated">-category
62warnings to alert you to this fact. To silence these deprecation warnings,
63install the modules in question from CPAN.
a8ba758d 64
25219f3f
KE
65Note that these are (with rare exceptions) fine modules that you are encouraged
66to continue to use. Their disinclusion from core primarily hinges on their
67necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68not usually on concerns over their design.
cf663f87 69
25219f3f 70=over
1b510166 71
25219f3f 72=item XXX
1b510166 73
25219f3f
KE
74XXX Note that deprecated modules should be listed here even if they are listed
75as an updated module in the L</Modules and Pragmata> section.
8ed1839e 76
25219f3f 77=back
8ed1839e 78
25219f3f 79[ List each other deprecation as a =head2 entry ]
8ed1839e 80
25219f3f 81=head1 Performance Enhancements
8ed1839e 82
25219f3f
KE
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
8ed1839e 85
25219f3f 86[ List each enhancement as an =item entry ]
8ed1839e 87
25219f3f 88=over 4
d912eab8 89
7d65f652
FC
90=item *
91
25219f3f 92XXX
7d65f652 93
c83a3d01 94=back
d912eab8 95
c83a3d01 96=head1 Modules and Pragmata
af94b3ac 97
25219f3f
KE
98XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
99go here. If Module::CoreList is updated, generate an initial draft of the
100following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
101for important changes should then be added by hand. In an ideal world,
102dual-life modules would have a F<Changes> file that could be cribbed.
9b78f210 103
25219f3f
KE
104The list of new and updated modules is modified automatically as part of
105preparing a Perl release, so the only reason to manually add entries here is if
106you're summarising the important changes in the module update. (Also, if the
107manually-added details don't match the automatically-generated ones, the
108release manager will have to investigate the situation carefully.)
9b78f210 109
25219f3f 110[ Within each section, list entries as an =item entry ]
1218f5ba 111
25219f3f 112=head2 New Modules and Pragmata
e6a2e5ca
SH
113
114=over 4
64b9a139
SH
115
116=item *
117
25219f3f 118XXX Remove this section if not applicable.
b2a6778b 119
25219f3f 120=back
b2a6778b 121
25219f3f 122=head2 Updated Modules and Pragmata
b2a6778b 123
25219f3f 124=over 4
b2a6778b
KE
125
126=item *
127
25219f3f 128L<XXX> has been upgraded from version A.xx to B.yy.
b2a6778b 129
25219f3f 130If there was something important to note about this change, include that here.
b2a6778b 131
25219f3f 132=back
b2a6778b 133
25219f3f 134=head2 Removed Modules and Pragmata
b2a6778b 135
25219f3f 136=over 4
b2a6778b
KE
137
138=item *
139
25219f3f 140XXX
ad3f654c 141
25219f3f 142=back
7358a033 143
25219f3f 144=head1 Documentation
64b9a139 145
25219f3f
KE
146XXX Changes to files in F<pod/> go here. Consider grouping entries by
147file and be sure to link to the appropriate page, e.g. L<perlfunc>.
e6a2e5ca 148
25219f3f 149=head2 New Documentation
b2a6778b 150
25219f3f 151XXX Changes which create B<new> files in F<pod/> go here.
b2a6778b 152
25219f3f 153=head3 L<XXX>
b2a6778b 154
25219f3f 155XXX Description of the purpose of the new file here
b2a6778b 156
25219f3f 157=head2 Changes to Existing Documentation
b2a6778b 158
25219f3f
KE
159We have attempted to update the documentation to reflect the changes
160listed in this document. If you find any we have missed, send email
161to L<perlbug@perl.org|mailto:perlbug@perl.org>.
b2a6778b 162
25219f3f
KE
163XXX Changes which significantly change existing files in F<pod/> go here.
164However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
165section.
b2a6778b 166
25219f3f 167Additionally, the following selected changes have been made:
b2a6778b 168
25219f3f 169=head3 L<XXX>
b2a6778b 170
25219f3f 171=over 4
b2a6778b
KE
172
173=item *
174
25219f3f 175XXX Description of the change here
b2a6778b 176
25219f3f 177=back
b2a6778b 178
25219f3f 179=head1 Diagnostics
b2a6778b 180
25219f3f
KE
181The following additions or changes have been made to diagnostic output,
182including warnings and fatal error messages. For the complete list of
183diagnostic messages, see L<perldiag>.
b2a6778b 184
25219f3f
KE
185XXX New or changed warnings emitted by the core's C<C> code go here. Also
186include any changes in L<perldiag> that reconcile it to the C<C> code.
b2a6778b 187
25219f3f 188=head2 New Diagnostics
b2a6778b 189
25219f3f
KE
190XXX Newly added diagnostic messages go under here, separated into New Errors
191and New Warnings
b2a6778b 192
25219f3f 193=head3 New Errors
b2a6778b 194
25219f3f 195=over 4
b2a6778b
KE
196
197=item *
198
25219f3f 199XXX L<message|perldiag/"message">
b2a6778b 200
25219f3f 201=back
b2a6778b 202
25219f3f 203=head3 New Warnings
b2a6778b 204
25219f3f 205=over 4
64b9a139
SH
206
207=item *
208
25219f3f 209XXX L<message|perldiag/"message">
64b9a139 210
e6a2e5ca 211=back
64b9a139 212
25219f3f 213=head2 Changes to Existing Diagnostics
64b9a139 214
25219f3f 215XXX Changes (i.e. rewording) of diagnostic messages go here
e6a2e5ca 216
04f89ea7
Z
217=over 4
218
64b9a139
SH
219=item *
220
25219f3f 221XXX Describe change here
2b8b74b0 222
25219f3f 223=back
e509fc38 224
25219f3f 225=head1 Utility Changes
e509fc38 226
25219f3f
KE
227XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
228Most of these are built within the directory F<utils>.
64b9a139 229
25219f3f
KE
230[ List utility changes as a =head2 entry for each utility and =item
231entries for each change
232Use L<XXX> with program names to get proper documentation linking. ]
64b9a139 233
25219f3f 234=head2 L<XXX>
64b9a139 235
25219f3f 236=over 4
64b9a139
SH
237
238=item *
239
25219f3f 240XXX
64b9a139 241
e6a2e5ca
SH
242=back
243
25219f3f 244=head1 Configuration and Compilation
64b9a139 245
25219f3f
KE
246XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
247go here. Any other changes to the Perl build process should be listed here.
248However, any platform-specific changes should be listed in the
249L</Platform Support> section, instead.
e6a2e5ca 250
25219f3f 251[ List changes as an =item entry ].
64b9a139 252
e6a2e5ca 253=over 4
64b9a139
SH
254
255=item *
256
25219f3f 257XXX
f99042c8 258
e6a2e5ca
SH
259=back
260
25219f3f 261=head1 Testing
e6a2e5ca 262
25219f3f
KE
263XXX Any significant changes to the testing of a freshly built perl should be
264listed here. Changes which create B<new> files in F<t/> go here as do any
265large changes to the testing harness (e.g. when parallel testing was added).
266Changes to existing files in F<t/> aren't worth summarizing, although the bugs
267that they represent may be covered elsewhere.
e6a2e5ca 268
25219f3f 269XXX If there were no significant test changes, say this:
64b9a139 270
25219f3f
KE
271Tests were added and changed to reflect the other additions and changes
272in this release.
64b9a139 273
25219f3f 274XXX If instead there were significant changes, say this:
e6a2e5ca 275
25219f3f
KE
276Tests were added and changed to reflect the other additions and
277changes in this release. Furthermore, these significant changes were
278made:
e6a2e5ca 279
25219f3f 280[ List each test improvement as an =item entry ]
e6a2e5ca 281
e6a2e5ca 282=over 4
64b9a139 283
25219f3f 284=item *
dea26044 285
25219f3f 286XXX
dea26044 287
25219f3f 288=back
dea26044 289
25219f3f 290=head1 Platform Support
dea26044 291
25219f3f 292XXX Any changes to platform support should be listed in the sections below.
dea26044 293
25219f3f
KE
294[ Within the sections, list each platform as an =item entry with specific
295changes as paragraphs below it. ]
dea26044 296
25219f3f 297=head2 New Platforms
dea26044 298
25219f3f
KE
299XXX List any platforms that this version of perl compiles on, that previous
300versions did not. These will either be enabled by new files in the F<hints/>
301directories, or new subdirectories and F<README> files at the top level of the
302source tree.
dea26044 303
25219f3f 304=over 4
dea26044 305
25219f3f 306=item XXX-some-platform
dea26044 307
25219f3f 308XXX
dea26044
MB
309
310=back
e6a2e5ca 311
e6a2e5ca
SH
312=head2 Discontinued Platforms
313
25219f3f
KE
314XXX List any platforms that this version of perl no longer compiles on.
315
e6a2e5ca
SH
316=over 4
317
25219f3f 318=item XXX-some-platform
e6a2e5ca 319
25219f3f 320XXX
e6a2e5ca
SH
321
322=back
323
a8ba758d
JSA
324=head2 Platform-Specific Notes
325
25219f3f
KE
326XXX List any changes for specific platforms. This could include configuration
327and compilation changes or changes in portability/compatibility. However,
328changes within modules for platforms should generally be listed in the
329L</Modules and Pragmata> section.
330
a8ba758d 331=over 4
9ef07b78 332
25219f3f 333=item XXX-some-platform
a8ba758d 334
25219f3f 335XXX
a8ba758d
JSA
336
337=back
338
e6a2e5ca
SH
339=head1 Internal Changes
340
25219f3f
KE
341XXX Changes which affect the interface available to C<XS> code go here. Other
342significant internal changes for future core maintainers should be noted as
343well.
8ed1839e 344
25219f3f 345[ List each change as an =item entry ]
8ed1839e 346
25219f3f 347=over 4
a8ba758d 348
ee5287f6
LM
349=item *
350
25219f3f 351XXX
ee5287f6 352
e6a2e5ca
SH
353=back
354
355=head1 Selected Bug Fixes
356
25219f3f
KE
357XXX Important bug fixes in the core language are summarized here. Bug fixes in
358files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
a155eb05 359
25219f3f 360[ List each fix as an =item entry ]
c2bb91f9 361
25219f3f 362=over 4
e6a2e5ca 363
4faa3060
TC
364=item *
365
25219f3f 366XXX
4faa3060 367
25219f3f 368=back
4faa3060 369
25219f3f 370=head1 Known Problems
4faa3060 371
25219f3f
KE
372XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
373tests that had to be C<TODO>ed for the release would be noted here. Unfixed
374platform specific bugs also go here.
d1ac83c4 375
25219f3f 376[ List each fix as an =item entry ]
d1ac83c4 377
25219f3f 378=over 4
c4f4b223
Z
379
380=item *
381
25219f3f 382XXX
02d43d4f 383
e6a2e5ca
SH
384=back
385
e6a2e5ca
SH
386=head1 Errata From Previous Releases
387
388=over 4
8abafd33 389
e6a2e5ca
SH
390=item *
391
25219f3f
KE
392XXX Add anything here that we forgot to add, or were mistaken about, in
393the perldelta of a previous release.
8abafd33 394
e6a2e5ca 395=back
b2e49ab9 396
25219f3f 397=head1 Obituary
060724e5 398
25219f3f
KE
399XXX If any significant core contributor or member of the CPAN community has
400died, add a short obituary here.
060724e5 401
25219f3f 402=head1 Acknowledgements
060724e5 403
25219f3f 404XXX Generate this with:
060724e5 405
25219f3f 406 perl Porting/acknowledgements.pl v5.27.6..HEAD
f5b73711 407
44691e6f
AB
408=head1 Reporting Bugs
409
b5cbfe35
S
410If you find what you think is a bug, you might check the perl bug database
411at L<https://rt.perl.org/> . There may also be information at
412L<http://www.perl.org/> , the Perl Home Page.
44691e6f 413
e08634c5
SH
414If you believe you have an unreported bug, please run the L<perlbug> program
415included with your release. Be sure to trim your bug down to a tiny but
416sufficient test case. Your bug report, along with the output of C<perl -V>,
b5cbfe35 417will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 418
87c118b9
DM
419If the bug you are reporting has security implications which make it
420inappropriate to send to a publicly archived mailing list, then see
c0ea3294
SH
421L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
422for details of how to report the issue.
44691e6f 423
390ae6f9
S
424=head1 Give Thanks
425
426If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
427you can do so by running the C<perlthanks> program:
428
429 perlthanks
430
431This will send an email to the Perl 5 Porters list with your show of thanks.
432
44691e6f
AB
433=head1 SEE ALSO
434
e08634c5
SH
435The F<Changes> file for an explanation of how to view exhaustive details on
436what changed.
44691e6f
AB
437
438The F<INSTALL> file for how to build Perl.
439
440The F<README> file for general stuff.
441
442The F<Artistic> and F<Copying> files for copyright information.
443
444=cut