This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
regcomp.c: Add macro for generating deprecated warnings
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
19718730
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.17.9
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
19718730 12This document describes differences between the 5.17.8 release and the 5.17.9
e08634c5 13release.
6db9054f 14
19718730
AC
15If you are upgrading from an earlier release such as 5.17.7, first read
16L<perl5178delta>, which describes differences between 5.17.7 and 5.17.8.
17
18=head1 Notice
19
20XXX Any important notices here
bde9e88d 21
6253ee75 22=head1 Core Enhancements
dd271d7a 23
19718730
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 ]
29
30=head1 Security
31
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.
35
36[ List each security issue as a =head2 entry ]
9d1a5160 37
19718730
AC
38=head1 Incompatible Changes
39
40XXX 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 ]
9d1a5160 47
0e55f0d7 48=head1 Deprecations
3ef6ec90 49
19718730
AC
50XXX Any deprecated features, syntax, modules etc. should be listed here. In
51particular, deprecated modules should be listed here even if they are listed as
52an updated module in the L</Modules and Pragmata> section.
4d68ffa0 53
19718730
AC
54[ List each deprecation as a =head2 entry ]
55
56=head1 Performance Enhancements
57
58XXX Changes which enhance performance without changing behaviour go here.
59There may well be none in a stable release.
751611d4 60
19718730 61[ List each enhancement as a =item entry ]
751611d4 62
6253ee75 63=over 4
751611d4
FC
64
65=item *
66
19718730
AC
67XXX
68
69=back
70
71=head1 Modules and Pragmata
72
73XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
74go here. If Module::CoreList is updated, generate an initial draft of the
75following sections using F<Porting/corelist-perldelta.pl>, which prints stub
76entries to STDOUT. Results can be pasted in place of the '=head2' entries
77below. A paragraph summary for important changes should then be added by hand.
78In an ideal world, dual-life modules would have a F<Changes> file that could be
79cribbed.
80
81[ Within each section, list entries as a =item entry ]
82
83=head2 New Modules and Pragmata
751611d4 84
6253ee75 85=over 4
751611d4
FC
86
87=item *
88
19718730 89XXX
751611d4 90
19718730 91=back
86148eee 92
19718730
AC
93=head2 Updated Modules and Pragmata
94
95=over 4
7a7a10c7 96
e14ac59b 97=item *
7a7a10c7 98
19718730 99L<XXX> has been upgraded from version A.xx to B.yy.
7a7a10c7 100
19718730
AC
101=back
102
103=head2 Removed Modules and Pragmata
c387386a 104
19718730 105=over 4
32209f41 106
e14ac59b 107=item *
5faa50e9 108
19718730 109XXX
b7c7d786 110
6253ee75 111=back
b7c7d786 112
19718730 113=head1 Documentation
11e375e0 114
19718730
AC
115XXX Changes to files in F<pod/> go here. Consider grouping entries by
116file and be sure to link to the appropriate page, e.g. L<perlfunc>.
e498bd59 117
19718730
AC
118=head2 New Documentation
119
120XXX Changes which create B<new> files in F<pod/> go here.
e498bd59 121
19718730
AC
122=head3 L<XXX>
123
124XXX Description of the purpose of the new file here
125
126=head2 Changes to Existing Documentation
127
128XXX Changes which significantly change existing files in F<pod/> go here.
129However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
130section.
131
132=head3 L<XXX>
133
134=over 4
dd4b1c75
AC
135
136=item *
137
19718730 138XXX Description of the change here
cb077ed2 139
5d8c8c8a 140=back
5f877a7f 141
e14ac59b
RS
142=head1 Diagnostics
143
144The following additions or changes have been made to diagnostic output,
145including warnings and fatal error messages. For the complete list of
146diagnostic messages, see L<perldiag>.
1ea91bbe 147
19718730
AC
148XXX New or changed warnings emitted by the core's C<C> code go here. Also
149include any changes in L<perldiag> that reconcile it to the C<C> code.
150
6253ee75
DR
151=head2 New Diagnostics
152
19718730
AC
153XXX Newly added diagnostic messages go under here, separated into New Errors
154and New Warnings
155
156=head3 New Errors
11e375e0 157
e14ac59b 158=over 4
11e375e0
FC
159
160=item *
161
19718730
AC
162XXX L<message|perldiag/"message">
163
164=back
165
166=head3 New Warnings
167
168=over 4
5e0a247b
KW
169
170=item *
171
19718730
AC
172XXX L<message|perldiag/"message">
173
174=back
175
176=head2 Changes to Existing Diagnostics
177
178XXX Changes (i.e. rewording) of diagnostic messages go here
179
180=over 4
e14ac59b 181
6253ee75 182=item *
8b877d20 183
19718730
AC
184XXX Describe change here
185
186=back
187
188=head1 Utility Changes
189
190XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
191Most of these are built within the directories F<utils> and F<x2p>.
192
193[ List utility changes as a =head3 entry for each utility and =item
194entries for each change
195Use L<XXX> with program names to get proper documentation linking. ]
196
197=head3 L<XXX>
198
199=over 4
e078d89d
FC
200
201=item *
202
19718730 203XXX
e078d89d 204
6253ee75 205=back
e078d89d 206
19718730
AC
207=head1 Configuration and Compilation
208
209XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
210go here. Any other changes to the Perl build process should be listed here.
211However, any platform-specific changes should be listed in the
212L</Platform Support> section, instead.
213
214[ List changes as a =item entry ].
e078d89d 215
6253ee75 216=over 4
e078d89d 217
b7c7d786
FC
218=item *
219
19718730
AC
220XXX
221
222=back
223
224=head1 Testing
225
226XXX Any significant changes to the testing of a freshly built perl should be
227listed here. Changes which create B<new> files in F<t/> go here as do any
228large changes to the testing harness (e.g. when parallel testing was added).
229Changes to existing files in F<t/> aren't worth summarizing, although the bugs
230that they represent may be covered elsewhere.
231
232[ List each test improvement as a =item entry ]
233
234=over 4
e14ac59b 235
fdea6f98
FC
236=item *
237
19718730 238XXX
fdea6f98 239
6253ee75 240=back
7cf3104f 241
6253ee75 242=head1 Platform Support
7cf3104f 243
19718730
AC
244XXX Any changes to platform support should be listed in the sections below.
245
246[ Within the sections, list each platform as a =item entry with specific
247changes as paragraphs below it. ]
248
249=head2 New Platforms
250
251XXX List any platforms that this version of perl compiles on, that previous
252versions did not. These will either be enabled by new files in the F<hints/>
253directories, or new subdirectories and F<README> files at the top level of the
254source tree.
a0e45bac 255
6253ee75 256=over 4
139353f8 257
19718730 258=item XXX-some-platform
139353f8 259
19718730 260XXX
ba535ffe 261
6253ee75 262=back
ba535ffe 263
19718730
AC
264=head2 Discontinued Platforms
265
266XXX List any platforms that this version of perl no longer compiles on.
52c09c59 267
6253ee75 268=over 4
12b847a2 269
19718730
AC
270=item XXX-some-platform
271
272XXX
12b847a2 273
19718730
AC
274=back
275
276=head2 Platform-Specific Notes
277
278XXX List any changes for specific platforms. This could include configuration
279and compilation changes or changes in portability/compatibility. However,
280changes within modules for platforms should generally be listed in the
281L</Modules and Pragmata> section.
282
283=over 4
6e50262c 284
19718730 285=item XXX-some-platform
6e50262c 286
19718730 287XXX
785fb813 288
0e55f0d7 289=back
785fb813 290
0e55f0d7 291=head1 Internal Changes
f5778209 292
19718730
AC
293XXX Changes which affect the interface available to C<XS> code go here. Other
294significant internal changes for future core maintainers should be noted as
295well.
296
297[ List each change as a =item entry ]
298
6253ee75 299=over 4
f5778209 300
216cf7fc
DR
301=item *
302
19718730 303XXX
216cf7fc 304
6253ee75 305=back
216cf7fc 306
6253ee75 307=head1 Selected Bug Fixes
216cf7fc 308
19718730
AC
309XXX Important bug fixes in the core language are summarized here. Bug fixes in
310files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
216cf7fc 311
19718730 312[ List each fix as a =item entry ]
216cf7fc 313
19718730 314=over 4
216cf7fc 315
d76c0f4b
RS
316=item *
317
19718730 318XXX
d76c0f4b 319
6253ee75 320=back
6c042f06 321
6253ee75 322=head1 Known Problems
6c042f06 323
19718730
AC
324XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
325tests that had to be C<TODO>ed for the release would be noted here. Unfixed
326platform specific bugs also go here.
3cf48cac 327
19718730 328[ List each fix as a =item entry ]
3cf48cac 329
19718730 330=over 4
05bee12a 331
100e3bc8
AC
332=item *
333
19718730 334XXX
100e3bc8 335
6253ee75 336=back
f5b73711 337
19718730 338=head1 Obituary
f5b73711 339
19718730
AC
340XXX If any significant core contributor has died, we've added a short obituary
341here.
0e55f0d7 342
19718730 343=head1 Acknowledgements
f5b73711 344
19718730 345XXX Generate this with:
f5b73711 346
19718730 347 perl Porting/acknowledgements.pl v5.17.8..HEAD
f5b73711 348
44691e6f
AB
349=head1 Reporting Bugs
350
e08634c5
SH
351If you find what you think is a bug, you might check the articles recently
352posted to the comp.lang.perl.misc newsgroup and the perl bug database at
353http://rt.perl.org/perlbug/ . There may also be information at
354http://www.perl.org/ , the Perl Home Page.
44691e6f 355
e08634c5
SH
356If you believe you have an unreported bug, please run the L<perlbug> program
357included with your release. Be sure to trim your bug down to a tiny but
358sufficient test case. Your bug report, along with the output of C<perl -V>,
359will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
360
361If the bug you are reporting has security implications, which make it
e08634c5
SH
362inappropriate to send to a publicly archived mailing list, then please send it
363to perl5-security-report@perl.org. This points to a closed subscription
364unarchived mailing list, which includes all the core committers, who will be
365able to help assess the impact of issues, figure out a resolution, and help
f9001595 366co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
367platforms on which Perl is supported. Please only use this address for
368security issues in the Perl core, not for modules independently distributed on
369CPAN.
44691e6f
AB
370
371=head1 SEE ALSO
372
e08634c5
SH
373The F<Changes> file for an explanation of how to view exhaustive details on
374what changed.
44691e6f
AB
375
376The F<INSTALL> file for how to build Perl.
377
378The F<README> file for general stuff.
379
380The F<Artistic> and F<Copying> files for copyright information.
381
382=cut