This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Notes in perldelta for the tiny XS-visible changes of the pack refactoring.
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
583aa5c2
RS
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.19.1
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
583aa5c2 12This document describes differences between the 5.19.0 release and the 5.19.1
e08634c5 13release.
6db9054f 14
e9912eaa 15=head1 Notice
5ed58cbd 16
583aa5c2
RS
17XXX Any important notices here
18
19=head1 Core Enhancements
20
21XXX New core language features go here. Summarize user-visible core language
22enhancements. Particularly prominent performance optimisations could go
23here, but most should go in the L</Performance Enhancements> section.
24
25[ List each enhancement as a =head2 entry ]
26
27=head1 Security
28
29XXX Any security-related notices go here. In particular, any security
30vulnerabilities closed should be noted here rather than in the
31L</Selected Bug Fixes> section.
32
33[ List each security issue as a =head2 entry ]
34
35=head1 Incompatible Changes
36
37XXX For a release on a stable branch, this section aspires to be:
38
39 There are no changes intentionally incompatible with 5.XXX.XXX
40 If any exist, they are bugs, and we request that you submit a
41 report. See L</Reporting Bugs> below.
42
43[ List each incompatible change as a =head2 entry ]
44
45=head1 Deprecations
46
47XXX Any deprecated features, syntax, modules etc. should be listed here.
48
49=head2 Module removals
50
51XXX Remove this section if inapplicable.
52
53The following modules will be removed from the core distribution in a future
54release, and will at that time need to be installed from CPAN. Distributions
55on CPAN which require these modules will need to list them as prerequisites.
56
57The core versions of these modules will now issue C<"deprecated">-category
58warnings to alert you to this fact. To silence these deprecation warnings,
59install the modules in question from CPAN.
60
61Note that these are (with rare exceptions) fine modules that you are encouraged
62to continue to use. Their disinclusion from core primarily hinges on their
63necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
64not usually on concerns over their design.
65
66XXX Note that deprecated modules should be listed here even if they are listed
67as an updated module in the L</Modules and Pragmata> section.
68
69=over
70
71=item *
72
73...
74
75=back
76
77[ List each other deprecation as a =head2 entry ]
78
79=head1 Performance Enhancements
80
81XXX Changes which enhance performance without changing behaviour go here.
82There may well be none in a stable release.
83
84[ List each enhancement as a =item entry ]
85
86=over 4
87
88=item *
89
90XXX
91
92=back
5ed58cbd 93
e9912eaa 94=head1 Modules and Pragmata
5ed58cbd 95
583aa5c2
RS
96XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
97go here. If Module::CoreList is updated, generate an initial draft of the
98following sections using F<Porting/corelist-perldelta.pl>, which prints stub
99entries to STDOUT. Results can be pasted in place of the '=head2' entries
100below. A paragraph summary for important changes should then be added by hand.
101In an ideal world, dual-life modules would have a F<Changes> file that could be
102cribbed.
103
104[ Within each section, list entries as a =item entry ]
105
106=head2 New Modules and Pragmata
107
108=over 4
109
110=item *
111
112XXX
113
114=back
115
e9912eaa 116=head2 Updated Modules and Pragmata
5ed58cbd 117
e9912eaa 118=over 4
5ed58cbd 119
e9912eaa 120=item *
5ed58cbd 121
dbd04185
NC
122Test::Harness has been upgraded from version 3.26 to 3.28
123
124Memory usage is dramatically reduced. t/harness now uses about 10% of the
125memory used by 3.26 and earlier.
126
127C<PERL5LIB> is always propagated to a test's C<@INC>, even under C<-T>.
583aa5c2
RS
128
129=back
130
131=head2 Removed Modules and Pragmata
132
133=over 4
5ed58cbd 134
e9912eaa 135=item *
5ed58cbd 136
583aa5c2
RS
137XXX
138
139=back
140
141=head1 Documentation
142
143XXX Changes to files in F<pod/> go here. Consider grouping entries by
144file and be sure to link to the appropriate page, e.g. L<perlfunc>.
145
146=head2 New Documentation
147
148XXX Changes which create B<new> files in F<pod/> go here.
149
150=head3 L<XXX>
151
152XXX Description of the purpose of the new file here
153
154=head2 Changes to Existing Documentation
155
156XXX Changes which significantly change existing files in F<pod/> go here.
157However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
158section.
159
160=head3 L<XXX>
161
162=over 4
1993add8 163
e9912eaa 164=item *
ec985017 165
583aa5c2
RS
166XXX Description of the change here
167
168=back
169
170=head1 Diagnostics
171
172The following additions or changes have been made to diagnostic output,
173including warnings and fatal error messages. For the complete list of
174diagnostic messages, see L<perldiag>.
175
176XXX New or changed warnings emitted by the core's C<C> code go here. Also
177include any changes in L<perldiag> that reconcile it to the C<C> code.
178
179=head2 New Diagnostics
180
181XXX Newly added diagnostic messages go under here, separated into New Errors
182and New Warnings
183
184=head3 New Errors
185
186=over 4
71e6aba6
RS
187
188=item *
189
583aa5c2
RS
190XXX L<message|perldiag/"message">
191
192=back
193
194=head3 New Warnings
195
196=over 4
71e6aba6 197
d5f315e8
KW
198=item *
199
583aa5c2 200XXX L<message|perldiag/"message">
d5f315e8 201
337fb649 202=back
2426c394 203
583aa5c2 204=head2 Changes to Existing Diagnostics
e9912eaa 205
583aa5c2 206XXX Changes (i.e. rewording) of diagnostic messages go here
357b01df 207
583aa5c2 208=over 4
357b01df 209
583aa5c2 210=item *
357b01df 211
583aa5c2 212XXX Describe change here
357b01df 213
583aa5c2 214=back
357b01df 215
583aa5c2 216=head1 Utility Changes
357b01df 217
583aa5c2
RS
218XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
219Most of these are built within the directories F<utils> and F<x2p>.
357b01df 220
583aa5c2
RS
221[ List utility changes as a =head3 entry for each utility and =item
222entries for each change
223Use L<XXX> with program names to get proper documentation linking. ]
357b01df 224
583aa5c2 225=head3 L<XXX>
357b01df 226
583aa5c2 227=over 4
357b01df 228
583aa5c2 229=item *
357b01df 230
583aa5c2 231XXX
357b01df 232
583aa5c2
RS
233=back
234
235=head1 Configuration and Compilation
236
237XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
238go here. Any other changes to the Perl build process should be listed here.
239However, any platform-specific changes should be listed in the
240L</Platform Support> section, instead.
241
242[ List changes as a =item entry ].
243
244=over 4
245
246=item *
247
248XXX
357b01df 249
e9912eaa 250=back
357b01df 251
583aa5c2
RS
252=head1 Testing
253
254XXX Any significant changes to the testing of a freshly built perl should be
255listed here. Changes which create B<new> files in F<t/> go here as do any
256large changes to the testing harness (e.g. when parallel testing was added).
257Changes to existing files in F<t/> aren't worth summarizing, although the bugs
258that they represent may be covered elsewhere.
259
260[ List each test improvement as a =item entry ]
261
262=over 4
263
264=item *
265
266XXX
267
268=back
269
270=head1 Platform Support
271
272XXX Any changes to platform support should be listed in the sections below.
273
274[ Within the sections, list each platform as a =item entry with specific
275changes as paragraphs below it. ]
276
277=head2 New Platforms
278
279XXX List any platforms that this version of perl compiles on, that previous
280versions did not. These will either be enabled by new files in the F<hints/>
281directories, or new subdirectories and F<README> files at the top level of the
282source tree.
283
284=over 4
285
286=item XXX-some-platform
287
288XXX
289
290=back
291
292=head2 Discontinued Platforms
293
294XXX List any platforms that this version of perl no longer compiles on.
295
296=over 4
297
298=item XXX-some-platform
357b01df 299
583aa5c2 300XXX
5ed58cbd 301
583aa5c2
RS
302=back
303
304=head2 Platform-Specific Notes
305
306XXX List any changes for specific platforms. This could include configuration
307and compilation changes or changes in portability/compatibility. However,
308changes within modules for platforms should generally be listed in the
309L</Modules and Pragmata> section.
310
311=over 4
312
7df6ffa3 313=item Mixed-endian platforms
583aa5c2 314
7df6ffa3
NC
315The code supporting C<pack> and C<unpack> operations on mixed endian
316platforms has been removed. We believe that Perl has long been unable to
317build on mixed endian architectures (such as PDP-11s), so we don't think
318that this change will affect any platforms which are able to build v5.18.0.
583aa5c2
RS
319
320=back
321
322=head1 Internal Changes
323
324XXX Changes which affect the interface available to C<XS> code go here. Other
325significant internal changes for future core maintainers should be noted as
326well.
327
328[ List each change as a =item entry ]
329
330=over 4
331
332=item *
333
7df6ffa3
NC
334The functions C<my_swap>, C<my_htonl> and C<my_ntohl> have been removed.
335It is unclear why these functions were ever marked as I<A>, part of the
336API. XS code can't call them directly, as it can't rely on them being
337compiled. Unsurprisingly, no code on CPAN references them.
583aa5c2
RS
338
339=back
340
341=head1 Selected Bug Fixes
342
343XXX Important bug fixes in the core language are summarized here. Bug fixes in
344files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
5ed58cbd 345
583aa5c2 346[ List each fix as a =item entry ]
32b79602 347
583aa5c2
RS
348=over 4
349
350=item *
351
352XXX
353
354=back
355
356=head1 Known Problems
357
358XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
359tests that had to be C<TODO>ed for the release would be noted here. Unfixed
360platform specific bugs also go here.
361
362[ List each fix as a =item entry ]
363
364=over 4
365
366=item *
367
368XXX
369
370=back
371
372=head1 Obituary
373
374XXX If any significant core contributor has died, we've added a short obituary
375here.
376
377=head1 Acknowledgements
a75569c0 378
583aa5c2 379XXX Generate this with:
e9912eaa 380
583aa5c2 381 perl Porting/acknowledgements.pl v5.19.1..HEAD
f5b73711 382
44691e6f
AB
383=head1 Reporting Bugs
384
e08634c5
SH
385If you find what you think is a bug, you might check the articles recently
386posted to the comp.lang.perl.misc newsgroup and the perl bug database at
387http://rt.perl.org/perlbug/ . There may also be information at
388http://www.perl.org/ , the Perl Home Page.
44691e6f 389
e08634c5
SH
390If you believe you have an unreported bug, please run the L<perlbug> program
391included with your release. Be sure to trim your bug down to a tiny but
392sufficient test case. Your bug report, along with the output of C<perl -V>,
393will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
394
395If the bug you are reporting has security implications, which make it
e08634c5
SH
396inappropriate to send to a publicly archived mailing list, then please send it
397to perl5-security-report@perl.org. This points to a closed subscription
398unarchived mailing list, which includes all the core committers, who will be
399able to help assess the impact of issues, figure out a resolution, and help
f9001595 400co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
401platforms on which Perl is supported. Please only use this address for
402security issues in the Perl core, not for modules independently distributed on
403CPAN.
44691e6f
AB
404
405=head1 SEE ALSO
406
e08634c5
SH
407The F<Changes> file for an explanation of how to view exhaustive details on
408what changed.
44691e6f
AB
409
410The F<INSTALL> file for how to build Perl.
411
412The F<README> file for general stuff.
413
414The F<Artistic> and F<Copying> files for copyright information.
415
416=cut