This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta entry for Pod::Simple 3.32 to 3.35 upgrade.
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
733dba2b
CG
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.25.8
eabfc7bc 9
2cfe9b50 10=head1 DESCRIPTION
eabfc7bc 11
733dba2b 12This document describes differences between the 5.25.7 release and the 5.25.8
4b8803f0 13release.
f3ed8cbf 14
733dba2b
CG
15If you are upgrading from an earlier release such as 5.25.6, first read
16L<perl5257delta>, which describes differences between 5.25.6 and 5.25.7.
8bbdbfcb 17
733dba2b 18=head1 Notice
8bbdbfcb 19
733dba2b 20XXX Any important notices here
8bbdbfcb 21
733dba2b 22=head1 Core Enhancements
ce6646d7 23
733dba2b
CG
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.
c0ea3294 27
733dba2b 28[ List each enhancement as a =head2 entry ]
ce6646d7 29
eaed4a85
YO
30=head2 New Hash Function For 64-bit Builds
31
32We have switched to a hybrid hash function to better balance
33performance for short and long keys.
34
35For short keys, 16 bytes and under, we use an optimised variant of
36One At A Time Hard, and for longer keys we use Siphash 1-3. For very
37long keys this is a big improvement in performance. For shorter keys
38there is a modest improvement.
39
733dba2b 40=head1 Security
8bbdbfcb 41
733dba2b
CG
42XXX Any security-related notices go here. In particular, any security
43vulnerabilities closed should be noted here rather than in the
44L</Selected Bug Fixes> section.
8bbdbfcb 45
733dba2b 46[ List each security issue as a =head2 entry ]
8bbdbfcb 47
733dba2b 48=head1 Incompatible Changes
8bbdbfcb 49
733dba2b 50XXX For a release on a stable branch, this section aspires to be:
2f4cbc09 51
733dba2b
CG
52 There are no changes intentionally incompatible with 5.XXX.XXX
53 If any exist, they are bugs, and we request that you submit a
54 report. See L</Reporting Bugs> below.
2f4cbc09 55
733dba2b 56[ List each incompatible change as a =head2 entry ]
226eba01 57
733dba2b 58=head1 Deprecations
8bbdbfcb 59
733dba2b 60XXX Any deprecated features, syntax, modules etc. should be listed here.
8bbdbfcb 61
733dba2b 62=head2 Module removals
8bbdbfcb 63
733dba2b 64XXX Remove this section if inapplicable.
8bbdbfcb 65
733dba2b
CG
66The following modules will be removed from the core distribution in a
67future release, and will at that time need to be installed from CPAN.
68Distributions on CPAN which require these modules will need to list them as
69prerequisites.
8bbdbfcb 70
733dba2b
CG
71The core versions of these modules will now issue C<"deprecated">-category
72warnings to alert you to this fact. To silence these deprecation warnings,
73install the modules in question from CPAN.
8bbdbfcb 74
733dba2b
CG
75Note that these are (with rare exceptions) fine modules that you are encouraged
76to continue to use. Their disinclusion from core primarily hinges on their
77necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
78not usually on concerns over their design.
8bbdbfcb 79
733dba2b 80=over
8bbdbfcb 81
733dba2b 82=item XXX
8bbdbfcb 83
733dba2b
CG
84XXX Note that deprecated modules should be listed here even if they are listed
85as an updated module in the L</Modules and Pragmata> section.
8bbdbfcb 86
a09f502b 87=back
226eba01 88
733dba2b 89[ List each other deprecation as a =head2 entry ]
55a729d3 90
733dba2b 91=head1 Performance Enhancements
226eba01 92
733dba2b
CG
93XXX Changes which enhance performance without changing behaviour go here.
94There may well be none in a stable release.
226eba01 95
733dba2b 96[ List each enhancement as a =item entry ]
8bbdbfcb
CG
97
98=over 4
99
eaed4a85 100=item * New Faster Hash Function on 64 bit builds
8bbdbfcb 101
eaed4a85
YO
102We use a different hash function for short and long keys. This should
103improve performance and security, especially for long keys.
8bbdbfcb 104
dd3d2a3f
DM
105=item * readline is faster
106
107Reading from a file line-by-line with c<readline()> or C<< <> >> should
108now typically be faster due to a better implementation of the code that
109searches for the next newline character.
110
8bbdbfcb
CG
111=back
112
733dba2b 113=head1 Modules and Pragmata
8bbdbfcb 114
733dba2b
CG
115XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
116go here. If Module::CoreList is updated, generate an initial draft of the
117following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
118for important changes should then be added by hand. In an ideal world,
119dual-life modules would have a F<Changes> file that could be cribbed.
8bbdbfcb 120
733dba2b 121[ Within each section, list entries as a =item entry ]
8bbdbfcb 122
733dba2b 123=head2 New Modules and Pragmata
226eba01 124
a09f502b 125=over 4
226eba01
AC
126
127=item *
128
733dba2b 129XXX
8bbdbfcb
CG
130
131=back
132
733dba2b 133=head2 Updated Modules and Pragmata
8bbdbfcb
CG
134
135=over 4
136
137=item *
138
733dba2b 139L<XXX> has been upgraded from version A.xx to B.yy.
8bbdbfcb 140
ff10d69b
JK
141=item *
142
143L<Pod::Simple> has been upgraded from version 3.32 to 3.35.
144
8bbdbfcb
CG
145=back
146
733dba2b 147=head2 Removed Modules and Pragmata
8bbdbfcb
CG
148
149=over 4
150
151=item *
152
733dba2b 153XXX
8bbdbfcb
CG
154
155=back
156
733dba2b 157=head1 Documentation
8bbdbfcb 158
733dba2b
CG
159XXX Changes to files in F<pod/> go here. Consider grouping entries by
160file and be sure to link to the appropriate page, e.g. L<perlfunc>.
8bbdbfcb 161
733dba2b 162=head2 New Documentation
8bbdbfcb 163
733dba2b 164XXX Changes which create B<new> files in F<pod/> go here.
8bbdbfcb 165
733dba2b 166=head3 L<XXX>
8bbdbfcb 167
733dba2b 168XXX Description of the purpose of the new file here
8bbdbfcb 169
733dba2b 170=head2 Changes to Existing Documentation
8bbdbfcb 171
733dba2b
CG
172XXX Changes which significantly change existing files in F<pod/> go here.
173However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
174section.
8bbdbfcb 175
733dba2b 176=head3 L<XXX>
8bbdbfcb
CG
177
178=over 4
179
180=item *
181
733dba2b 182XXX Description of the change here
8bbdbfcb
CG
183
184=back
185
733dba2b 186=head1 Diagnostics
8bbdbfcb 187
733dba2b
CG
188The following additions or changes have been made to diagnostic output,
189including warnings and fatal error messages. For the complete list of
190diagnostic messages, see L<perldiag>.
8bbdbfcb 191
733dba2b
CG
192XXX New or changed warnings emitted by the core's C<C> code go here. Also
193include any changes in L<perldiag> that reconcile it to the C<C> code.
8bbdbfcb 194
733dba2b 195=head2 New Diagnostics
8bbdbfcb 196
733dba2b
CG
197XXX Newly added diagnostic messages go under here, separated into New Errors
198and New Warnings
8bbdbfcb 199
733dba2b 200=head3 New Errors
8bbdbfcb
CG
201
202=over 4
203
204=item *
205
733dba2b 206XXX L<message|perldiag/"message">
8bbdbfcb
CG
207
208=back
209
733dba2b 210=head3 New Warnings
8bbdbfcb
CG
211
212=over 4
213
214=item *
215
733dba2b 216XXX L<message|perldiag/"message">
8bbdbfcb 217
be293293 218=back
8c3f6b0b 219
a09f502b
AC
220=head2 Changes to Existing Diagnostics
221
733dba2b 222XXX Changes (i.e. rewording) of diagnostic messages go here
2c4879e2 223
733dba2b 224=over 4
8bbdbfcb
CG
225
226=item *
227
733dba2b 228XXX Describe change here
bd5630ab 229
2c4879e2
SL
230=back
231
a09f502b
AC
232=head1 Utility Changes
233
733dba2b
CG
234XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
235Most of these are built within the directory F<utils>.
8bbdbfcb 236
733dba2b
CG
237[ List utility changes as a =head2 entry for each utility and =item
238entries for each change
239Use L<XXX> with program names to get proper documentation linking. ]
8bbdbfcb 240
733dba2b 241=head2 L<XXX>
8bbdbfcb 242
733dba2b 243=over 4
8bbdbfcb
CG
244
245=item *
246
733dba2b 247XXX
07cfdfcc 248
262514fd 249=back
2c4879e2 250
a09f502b
AC
251=head1 Configuration and Compilation
252
733dba2b
CG
253XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
254go here. Any other changes to the Perl build process should be listed here.
255However, any platform-specific changes should be listed in the
256L</Platform Support> section, instead.
8bbdbfcb 257
733dba2b 258[ List changes as a =item entry ].
8bbdbfcb 259
733dba2b 260=over 4
a09f502b 261
a07f6112 262=item *
a09f502b 263
733dba2b 264XXX
a09f502b 265
a07f6112 266=back
7d897bd0 267
a07f6112 268=head1 Testing
a09f502b 269
733dba2b
CG
270XXX Any significant changes to the testing of a freshly built perl should be
271listed here. Changes which create B<new> files in F<t/> go here as do any
272large changes to the testing harness (e.g. when parallel testing was added).
273Changes to existing files in F<t/> aren't worth summarizing, although the bugs
274that they represent may be covered elsewhere.
a6a32e96 275
733dba2b 276[ List each test improvement as a =item entry ]
a6a32e96 277
733dba2b 278=over 4
a6a32e96 279
e7e6e8d4
KW
280=item *
281
733dba2b 282XXX
e7e6e8d4 283
262514fd 284=back
046a081f 285
262514fd 286=head1 Platform Support
046a081f 287
733dba2b 288XXX Any changes to platform support should be listed in the sections below.
8bbdbfcb 289
733dba2b
CG
290[ Within the sections, list each platform as a =item entry with specific
291changes as paragraphs below it. ]
8bbdbfcb 292
733dba2b 293=head2 New Platforms
8bbdbfcb 294
733dba2b
CG
295XXX List any platforms that this version of perl compiles on, that previous
296versions did not. These will either be enabled by new files in the F<hints/>
297directories, or new subdirectories and F<README> files at the top level of the
298source tree.
8bbdbfcb 299
733dba2b 300=over 4
8bbdbfcb 301
733dba2b 302=item XXX-some-platform
a07f6112 303
733dba2b 304XXX
8bbdbfcb 305
733dba2b 306=back
8bbdbfcb 307
733dba2b 308=head2 Discontinued Platforms
8bbdbfcb 309
733dba2b 310XXX List any platforms that this version of perl no longer compiles on.
8bbdbfcb 311
733dba2b 312=over 4
8bbdbfcb 313
733dba2b 314=item XXX-some-platform
8bbdbfcb 315
733dba2b 316XXX
8bbdbfcb 317
733dba2b 318=back
8bbdbfcb 319
733dba2b 320=head2 Platform-Specific Notes
8bbdbfcb 321
733dba2b
CG
322XXX List any changes for specific platforms. This could include configuration
323and compilation changes or changes in portability/compatibility. However,
324changes within modules for platforms should generally be listed in the
325L</Modules and Pragmata> section.
8bbdbfcb 326
733dba2b 327=over 4
8bbdbfcb 328
733dba2b 329=item XXX-some-platform
8bbdbfcb 330
733dba2b 331XXX
8bbdbfcb
CG
332
333=back
334
a07f6112 335=head1 Internal Changes
f9380377 336
733dba2b
CG
337XXX Changes which affect the interface available to C<XS> code go here. Other
338significant internal changes for future core maintainers should be noted as
339well.
a6a32e96 340
733dba2b 341[ List each change as a =item entry ]
a6a32e96 342
733dba2b 343=over 4
a6a32e96
AC
344
345=item *
346
e03e82a0
DM
347A new API function, C<sv_set_undef(sv)>, has been added. This is
348equivalent to C<sv_setsv(sv, &PL_sv_undef)>, but is more efficient.
bd5630ab 349
a09f502b 350=back
a6a32e96 351
a09f502b 352=head1 Selected Bug Fixes
a6a32e96 353
733dba2b
CG
354XXX Important bug fixes in the core language are summarized here. Bug fixes in
355files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
a6a32e96 356
733dba2b 357[ List each fix as a =item entry ]
8bbdbfcb 358
733dba2b 359=over 4
8bbdbfcb
CG
360
361=item *
362
733dba2b 363XXX
2f4cbc09 364
733dba2b 365=back
8bbdbfcb 366
733dba2b 367=head1 Known Problems
8bbdbfcb 368
733dba2b
CG
369XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
370tests that had to be C<TODO>ed for the release would be noted here. Unfixed
371platform specific bugs also go here.
8bbdbfcb 372
733dba2b 373[ List each fix as a =item entry ]
8bbdbfcb 374
733dba2b 375=over 4
8bbdbfcb
CG
376
377=item *
378
733dba2b 379XXX
8bbdbfcb 380
733dba2b 381=back
8bbdbfcb 382
733dba2b 383=head1 Errata From Previous Releases
8bbdbfcb 384
733dba2b 385=over 4
8bbdbfcb
CG
386
387=item *
388
733dba2b
CG
389XXX Add anything here that we forgot to add, or were mistaken about, in
390the perldelta of a previous release.
8bbdbfcb 391
262514fd
SL
392=back
393
733dba2b 394=head1 Obituary
a6a32e96 395
733dba2b
CG
396XXX If any significant core contributor has died, we've added a short obituary
397here.
262514fd 398
733dba2b 399=head1 Acknowledgements
226eba01 400
733dba2b 401XXX Generate this with:
24528e8e 402
733dba2b 403 perl Porting/acknowledgements.pl v5.25.5..HEAD
f5b73711 404
44691e6f
AB
405=head1 Reporting Bugs
406
c0ea3294
SH
407If you find what you think is a bug, you might check the perl bug database
408at L<https://rt.perl.org/> . There may also be information at
4b8803f0 409L<http://www.perl.org/> , the Perl Home Page.
44691e6f 410
e08634c5
SH
411If you believe you have an unreported bug, please run the L<perlbug> program
412included with your release. Be sure to trim your bug down to a tiny but
413sufficient test case. Your bug report, along with the output of C<perl -V>,
414will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 415
87c118b9
DM
416If the bug you are reporting has security implications which make it
417inappropriate to send to a publicly archived mailing list, then see
c0ea3294
SH
418L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
419for details of how to report the issue.
44691e6f
AB
420
421=head1 SEE ALSO
422
e08634c5
SH
423The F<Changes> file for an explanation of how to view exhaustive details on
424what changed.
44691e6f
AB
425
426The F<INSTALL> file for how to build Perl.
427
428The F<README> file for general stuff.
429
430The F<Artistic> and F<Copying> files for copyright information.
431
432=cut