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