This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re-flow some sample text in the perldelta template to avoid an overlong line.
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
0890f1a5
FC
5[ this is a template for a new perldelta file. Any text flagged as
6XXX needs to be processed before release. ]
6e925ecb 7
0890f1a5 8perldelta - what is new for perl v5.15.1
f5938650 9
0890f1a5 10=head1 DESCRIPTION
760696b8 11
0890f1a5
FC
12This document describes differences between the 5.15.1 release and
13the 5.15.0 release.
760696b8 14
0890f1a5
FC
15If you are upgrading from an earlier release such as 5.14.0, first read
16L<perl5150delta>, which describes differences between 5.14.0 and
175.15.0.
760696b8 18
0890f1a5 19=head1 Notice
760696b8 20
0890f1a5 21XXX Any important notices here
6693394d 22
0890f1a5 23=head1 Core Enhancements
6693394d 24
0890f1a5
FC
25XXX New core language features go here. Summarise user-visible core language
26enhancements. Particularly prominent performance optimisations could go
27here, but most should go in the L</Performance Enhancements> section.
6693394d 28
0890f1a5 29[ List each enhancement as a =head2 entry ]
6693394d 30
5cd408a2
EB
31=head2 C<splice()> doesn't warn when truncating
32
33You can now limit the size of an array using C<splice(@a,MAX_LEN)> without
34worrying about warnings.
35
0890f1a5 36=head1 Security
6693394d 37
0890f1a5
FC
38XXX Any security-related notices go here. In particular, any security
39vulnerabilities closed should be noted here rather than in the
40L</Selected Bug Fixes> section.
b7188eb5 41
0890f1a5 42[ List each security issue as a =head2 entry ]
e8e35311 43
0890f1a5 44=head1 Incompatible Changes
2c389f6c 45
0890f1a5 46XXX For a release on a stable branch, this section aspires to be:
760696b8 47
307f4217
NC
48 There are no changes intentionally incompatible with 5.XXX.XXX
49 If any exist, they are bugs and reports are welcome.
760696b8 50
0890f1a5 51[ List each incompatible change as a =head2 entry ]
760696b8 52
0890f1a5 53=head1 Deprecations
760696b8 54
0890f1a5
FC
55XXX Any deprecated features, syntax, modules etc. should be listed here.
56In particular, deprecated modules should be listed here even if they are
57listed as an updated module in the L</Modules and Pragmata> section.
760696b8 58
0890f1a5 59[ List each deprecation as a =head2 entry ]
760696b8 60
0890f1a5 61=head1 Performance Enhancements
760696b8 62
0890f1a5
FC
63XXX Changes which enhance performance without changing behaviour go here. There
64may well be none in a stable release.
760696b8 65
0890f1a5 66[ List each enhancement as a =item entry ]
6693394d
FC
67
68=over 4
69
70=item *
71
0890f1a5 72XXX
6693394d
FC
73
74=back
75
0890f1a5 76=head1 Modules and Pragmata
bdb9ba77 77
0890f1a5
FC
78XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
79go here. If Module::CoreList is updated, generate an initial draft of the
80following sections using F<Porting/corelist-perldelta.pl>, which prints stub
81entries to STDOUT. Results can be pasted in place of the '=head2' entries
82below. A paragraph summary for important changes should then be added by hand.
83In an ideal world, dual-life modules would have a F<Changes> file that could be
84cribbed.
bdb9ba77 85
0890f1a5 86[ Within each section, list entries as a =item entry ]
bdb9ba77 87
0890f1a5 88=head2 New Modules and Pragmata
6693394d 89
0890f1a5 90=over 4
6693394d
FC
91
92=item *
93
0890f1a5 94XXX
6693394d
FC
95
96=back
97
0890f1a5 98=head2 Updated Modules and Pragmata
760696b8 99
0890f1a5 100=over 4
760696b8
FC
101
102=item *
103
0890f1a5 104L<XXX> has been upgraded from version 0.69 to version 0.70.
2c389f6c 105
e8e35311
FC
106=back
107
0890f1a5 108=head2 Removed Modules and Pragmata
bdb9ba77 109
0890f1a5 110=over 4
bdb9ba77
DG
111
112=item *
113
0890f1a5 114XXX
bdb9ba77
DG
115
116=back
117
0890f1a5 118=head1 Documentation
f5938650 119
0890f1a5
FC
120XXX Changes to files in F<pod/> go here. Consider grouping entries by
121file and be sure to link to the appropriate page, e.g. L<perlfunc>.
f5938650 122
0890f1a5 123=head2 New Documentation
f5938650 124
0890f1a5 125XXX Changes which create B<new> files in F<pod/> go here.
f5938650 126
0890f1a5 127=head3 L<XXX>
bdb9ba77 128
0890f1a5 129XXX Description of the purpose of the new file here
bdb9ba77 130
0890f1a5
FC
131=head2 Changes to Existing Documentation
132
133XXX Changes which significantly change existing files in F<pod/> go here.
134However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
135section.
f5938650 136
0890f1a5 137=head3 L<XXX>
6693394d 138
0890f1a5 139=over 4
6693394d
FC
140
141=item *
142
0890f1a5 143XXX Description of the change here
6693394d
FC
144
145=back
146
34dc2ec0 147=head1 Diagnostics
b7188eb5 148
34dc2ec0
DM
149The following additions or changes have been made to diagnostic output,
150including warnings and fatal error messages. For the complete list of
151diagnostic messages, see L<perldiag>.
44691e6f 152
0890f1a5
FC
153XXX New or changed warnings emitted by the core's C<C> code go here. Also
154include any changes in L<perldiag> that reconcile it to the C<C> code.
2c389f6c 155
0890f1a5
FC
156[ Within each section, list entries as a =item entry that links to perldiag,
157 e.g.
2c389f6c 158
0890f1a5 159 =item *
b7188eb5 160
0890f1a5
FC
161 L<Invalid version object|perldiag/"Invalid version object">
162]
5076a392 163
0890f1a5 164=head2 New Diagnostics
5076a392 165
0890f1a5 166XXX Newly added diagnostic messages go here
e8e35311 167
0890f1a5 168=head3 New Errors
5076a392 169
34dc2ec0 170=over 4
5076a392 171
e8e35311 172=item *
5076a392 173
0890f1a5 174XXX L<message|perldiag/"message">
a0ed52f4 175
bdb9ba77 176=back
bdab33d1 177
0890f1a5 178=head3 New Warnings
d430b8e7 179
0890f1a5 180=over 4
5076a392 181
bdb9ba77 182=item *
5076a392 183
0890f1a5 184XXX L<message|perldiag/"message">
5076a392 185
bdb9ba77 186=back
e8e35311 187
0890f1a5 188=head2 Changes to Existing Diagnostics
42a91c97 189
0890f1a5 190XXX Changes (i.e. rewording) of diagnostic messages go here
6693394d 191
34dc2ec0 192=over 4
42a91c97 193
6693394d 194=item *
42a91c97 195
0890f1a5 196XXX Describe change here
42a91c97 197
34dc2ec0 198=back
42a91c97 199
0890f1a5 200=head1 Utility Changes
69c6927c 201
0890f1a5
FC
202XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
203here. Most of these are built within the directories F<utils> and F<x2p>.
69c6927c 204
0890f1a5
FC
205[ List utility changes as a =head3 entry for each utility and =item
206entries for each change
207Use L<XXX> with program names to get proper documentation linking. ]
c13a5c80 208
0890f1a5 209=head3 L<XXX>
c13a5c80 210
0890f1a5 211=over 4
bdab33d1 212
571f0e86
NC
213=item *
214
0890f1a5 215XXX
384e62c0
DG
216
217=back
218
0890f1a5 219=head1 Configuration and Compilation
cdc10f43 220
0890f1a5
FC
221XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
222go here. Any other changes to the Perl build process should be listed here.
223However, any platform-specific changes should be listed in the
224L</Platform Support> section, instead.
cdc10f43 225
0890f1a5 226[ List changes as a =item entry ].
bdab33d1 227
34dc2ec0 228=over 4
d430b8e7
FC
229
230=item *
231
0890f1a5 232XXX
bdab33d1
DG
233
234=back
235
0890f1a5 236=head1 Testing
bdab33d1 237
0890f1a5
FC
238XXX Any significant changes to the testing of a freshly built perl should be
239listed here. Changes which create B<new> files in F<t/> go here as do any
240large changes to the testing harness (e.g. when parallel testing was added).
241Changes to existing files in F<t/> aren't worth summarising, although the bugs
242that they represent may be covered elsewhere.
f5938650 243
0890f1a5 244[ List each test improvement as a =item entry ]
f5938650 245
0890f1a5 246=over 4
f5938650
FC
247
248=item *
249
0890f1a5 250XXX
f5938650
FC
251
252=back
2fbb14a0 253
0890f1a5 254=head1 Platform Support
975dff8c 255
0890f1a5 256XXX Any changes to platform support should be listed in the sections below.
975dff8c 257
0890f1a5
FC
258[ Within the sections, list each platform as a =item entry with specific
259changes as paragraphs below it. ]
975dff8c 260
0890f1a5 261=head2 New Platforms
975dff8c 262
0890f1a5
FC
263XXX List any platforms that this version of perl compiles on, that previous
264versions did not. These will either be enabled by new files in the F<hints/>
265directories, or new subdirectories and F<README> files at the top level of the
266source tree.
975dff8c 267
0890f1a5 268=over 4
975dff8c 269
0890f1a5 270=item XXX-some-platform
975dff8c 271
0890f1a5 272XXX
975dff8c
FC
273
274=back
275
0890f1a5 276=head2 Discontinued Platforms
da507230 277
0890f1a5 278XXX List any platforms that this version of perl no longer compiles on.
da507230 279
0890f1a5 280=over 4
fad4a2e4 281
0890f1a5 282=item XXX-some-platform
4dbb339a 283
0890f1a5 284XXX
4dbb339a 285
975dff8c
FC
286=back
287
0890f1a5 288=head2 Platform-Specific Notes
6693394d 289
0890f1a5
FC
290XXX List any changes for specific platforms. This could include configuration
291and compilation changes or changes in portability/compatibility. However,
292changes within modules for platforms should generally be listed in the
293L</Modules and Pragmata> section.
6693394d 294
0890f1a5 295=over 4
6693394d 296
0890f1a5 297=item XXX-some-platform
6693394d 298
0890f1a5 299XXX
6693394d
FC
300
301=back
302
0890f1a5 303=head1 Internal Changes
6693394d 304
0890f1a5
FC
305XXX Changes which affect the interface available to C<XS> code go here.
306Other significant internal changes for future core maintainers should
307be noted as well.
bdab33d1 308
0890f1a5 309[ List each change as a =item entry ]
f5938650 310
0890f1a5 311=over 4
f5938650
FC
312
313=item *
314
0890f1a5 315XXX
f5938650 316
0890f1a5 317=back
25aa614d 318
0890f1a5 319=head1 Selected Bug Fixes
87d00a71 320
0890f1a5
FC
321XXX Important bug fixes in the core language are summarised here.
322Bug fixes in files in F<ext/> and F<lib/> are best summarised in
323L</Modules and Pragmata>.
87d00a71 324
0890f1a5 325[ List each fix as a =item entry ]
87d00a71 326
0890f1a5 327=over 4
87d00a71 328
da507230
FC
329=item *
330
0890f1a5 331XXX
da507230 332
42a91c97
FC
333=back
334
c71a852f 335=head1 Known Problems
44691e6f 336
0890f1a5
FC
337XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
338tests that had to be C<TODO>ed for the release would be noted here, unless
339they were specific to a particular platform (see below).
bda24d5c 340
0890f1a5
FC
341This is a list of some significant unfixed bugs, which are regressions
342from either 5.XXX.XXX or 5.XXX.XXX.
bda24d5c 343
0890f1a5 344[ List each fix as a =item entry ]
bdb9ba77 345
0890f1a5 346=over 4
014fb485 347
d8e9570c
DG
348=item *
349
0890f1a5 350XXX
d8e9570c 351
bdb9ba77 352=back
014fb485 353
0890f1a5
FC
354=head1 Obituary
355
356XXX If any significant core contributor has died, we've added a short obituary
357here.
44691e6f 358
44691e6f
AB
359=head1 Acknowledgements
360
0890f1a5 361XXX The list of people to thank goes here.
29cf780c 362
44691e6f
AB
363=head1 Reporting Bugs
364
365If you find what you think is a bug, you might check the articles
34dc2ec0 366recently posted to the comp.lang.perl.misc newsgroup and the perl
44691e6f
AB
367bug database at http://rt.perl.org/perlbug/ . There may also be
368information at http://www.perl.org/ , the Perl Home Page.
369
370If you believe you have an unreported bug, please run the L<perlbug>
371program included with your release. Be sure to trim your bug down
372to a tiny but sufficient test case. Your bug report, along with the
373output of C<perl -V>, will be sent off to perlbug@perl.org to be
374analysed by the Perl porting team.
375
376If the bug you are reporting has security implications, which make it
377inappropriate to send to a publicly archived mailing list, then please send
34dc2ec0 378it to perl5-security-report@perl.org. This points to a closed subscription
b4707b2a
FC
379unarchived mailing list, which includes
380all the core committers, who will be able
44691e6f
AB
381to help assess the impact of issues, figure out a resolution, and help
382co-ordinate the release of patches to mitigate or fix the problem across all
34dc2ec0
DM
383platforms on which Perl is supported. Please only use this address for
384security issues in the Perl core, not for modules independently
44691e6f
AB
385distributed on CPAN.
386
387=head1 SEE ALSO
388
389The F<Changes> file for an explanation of how to view exhaustive details
390on what changed.
391
392The F<INSTALL> file for how to build Perl.
393
394The F<README> file for general stuff.
395
396The F<Artistic> and F<Copying> files for copyright information.
397
398=cut