This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Relax fatal circumstances of unescaped '{'
[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.27.1
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.27.0 release and the 5.27.1
13 release.
14
15 If you are upgrading from an earlier release such as 5.26.0, first read
16 L<perl5270delta>, which describes differences between 5.26.0 and 5.27.0.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head1 Security
31
32 XXX Any security-related notices go here.  In particular, any security
33 vulnerabilities closed should be noted here rather than in the
34 L</Selected Bug Fixes> section.
35
36 [ List each security issue as a =head2 entry ]
37
38 =head1 Incompatible Changes
39
40 XXX 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 ]
47
48 =head2 Comma-less variable lists in formats are no longer allowed
49
50 Omitting the commas between variables passed to formats is no longer
51 allowed.  This has been deprecated since perl 5.000.
52
53 =head2 The C<:locked> and C<:unique> attributes have been removed
54
55 These have been no-ops and deprecated since perl 5.12 and 5.10,
56 respectively.
57
58 =head1 Deprecations
59
60 XXX Any deprecated features, syntax, modules etc. should be listed here.
61
62 =head2 Some uses of unescaped C<"{"> are no longer fatal
63
64 Perl 5.26.0 fatalized some uses of an unescaped left brace, but an
65 exception was made at the last minute, specifically crafted to be a
66 minimal change to allow GNU Autoconf to work.  This code is heavily
67 depended upon, and continues to use the deprecated usage.  Its use of an
68 unescaped left brace is one where we have no intention of repurposing
69 C<"{"> to be something other than itself.
70
71 That exception is now generalized to include various other such cases
72 where the C<"{"> will not be repurposed.  This is to get real experience
73 with this more complicated change now, in case we need to issue a dot
74 release if we find other things like Autoconf that are important to work
75 around.
76
77 Note that these uses continue to raise a deprecation message.
78
79 =head2 Module removals
80
81 XXX Remove this section if inapplicable.
82
83 The following modules will be removed from the core distribution in a
84 future release, and will at that time need to be installed from CPAN.
85 Distributions on CPAN which require these modules will need to list them as
86 prerequisites.
87
88 The core versions of these modules will now issue C<"deprecated">-category
89 warnings to alert you to this fact.  To silence these deprecation warnings,
90 install the modules in question from CPAN.
91
92 Note that these are (with rare exceptions) fine modules that you are encouraged
93 to continue to use.  Their disinclusion from core primarily hinges on their
94 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
95 not usually on concerns over their design.
96
97 =over
98
99 =item XXX
100
101 XXX Note that deprecated modules should be listed here even if they are listed
102 as an updated module in the L</Modules and Pragmata> section.
103
104 =back
105
106 [ List each other deprecation as a =head2 entry ]
107
108 =head1 Performance Enhancements
109
110 XXX Changes which enhance performance without changing behaviour go here.
111 There may well be none in a stable release.
112
113 [ List each enhancement as a =item entry ]
114
115 =over 4
116
117 =item *
118
119 XXX
120
121 =back
122
123 =head1 Modules and Pragmata
124
125 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
126 go here.  If Module::CoreList is updated, generate an initial draft of the
127 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
128 for important changes should then be added by hand.  In an ideal world,
129 dual-life modules would have a F<Changes> file that could be cribbed.
130
131 [ Within each section, list entries as a =item entry ]
132
133 =head2 New Modules and Pragmata
134
135 =over 4
136
137 =item *
138
139 XXX
140
141 =back
142
143 =head2 Updated Modules and Pragmata
144
145 =over 4
146
147 =item *
148
149 L<XXX> has been upgraded from version A.xx to B.yy.
150
151 =back
152
153 =head2 Removed Modules and Pragmata
154
155 =over 4
156
157 =item *
158
159 XXX
160
161 =back
162
163 =head1 Documentation
164
165 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
166 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
167
168 =head2 New Documentation
169
170 XXX Changes which create B<new> files in F<pod/> go here.
171
172 =head3 L<XXX>
173
174 XXX Description of the purpose of the new file here
175
176 =head2 Changes to Existing Documentation
177
178 XXX Changes which significantly change existing files in F<pod/> go here.
179 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
180 section.
181
182 =head3 L<XXX>
183
184 =over 4
185
186 =item *
187
188 XXX Description of the change here
189
190 =back
191
192 =head1 Diagnostics
193
194 The following additions or changes have been made to diagnostic output,
195 including warnings and fatal error messages.  For the complete list of
196 diagnostic messages, see L<perldiag>.
197
198 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
199 include any changes in L<perldiag> that reconcile it to the C<C> code.
200
201 =head2 New Diagnostics
202
203 XXX Newly added diagnostic messages go under here, separated into New Errors
204 and New Warnings
205
206 =head3 New Errors
207
208 =over 4
209
210 =item *
211
212 XXX L<message|perldiag/"message">
213
214 =back
215
216 =head3 New Warnings
217
218 =over 4
219
220 =item *
221
222 XXX L<message|perldiag/"message">
223
224 =back
225
226 =head2 Changes to Existing Diagnostics
227
228 XXX Changes (i.e. rewording) of diagnostic messages go here
229
230 =over 4
231
232 =item *
233
234 XXX Describe change here
235
236 =back
237
238 =head1 Utility Changes
239
240 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
241 Most of these are built within the directory F<utils>.
242
243 [ List utility changes as a =head2 entry for each utility and =item
244 entries for each change
245 Use L<XXX> with program names to get proper documentation linking. ]
246
247 =head2 L<XXX>
248
249 =over 4
250
251 =item *
252
253 XXX
254
255 =back
256
257 =head1 Configuration and Compilation
258
259 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
260 go here.  Any other changes to the Perl build process should be listed here.
261 However, any platform-specific changes should be listed in the
262 L</Platform Support> section, instead.
263
264 [ List changes as a =item entry ].
265
266 =over 4
267
268 =item *
269
270 XXX
271
272 =back
273
274 =head1 Testing
275
276 XXX Any significant changes to the testing of a freshly built perl should be
277 listed here.  Changes which create B<new> files in F<t/> go here as do any
278 large changes to the testing harness (e.g. when parallel testing was added).
279 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
280 that they represent may be covered elsewhere.
281
282 [ List each test improvement as a =item entry ]
283
284 =over 4
285
286 =item *
287
288 XXX
289
290 =back
291
292 =head1 Platform Support
293
294 XXX Any changes to platform support should be listed in the sections below.
295
296 [ Within the sections, list each platform as a =item entry with specific
297 changes as paragraphs below it. ]
298
299 =head2 New Platforms
300
301 XXX List any platforms that this version of perl compiles on, that previous
302 versions did not.  These will either be enabled by new files in the F<hints/>
303 directories, or new subdirectories and F<README> files at the top level of the
304 source tree.
305
306 =over 4
307
308 =item XXX-some-platform
309
310 XXX
311
312 =back
313
314 =head2 Discontinued Platforms
315
316 XXX List any platforms that this version of perl no longer compiles on.
317
318 =over 4
319
320 =item XXX-some-platform
321
322 XXX
323
324 =back
325
326 =head2 Platform-Specific Notes
327
328 XXX List any changes for specific platforms.  This could include configuration
329 and compilation changes or changes in portability/compatibility.  However,
330 changes within modules for platforms should generally be listed in the
331 L</Modules and Pragmata> section.
332
333 =over 4
334
335 =item XXX-some-platform
336
337 XXX
338
339 =back
340
341 =head1 Internal Changes
342
343 XXX Changes which affect the interface available to C<XS> code go here.  Other
344 significant internal changes for future core maintainers should be noted as
345 well.
346
347 [ List each change as a =item entry ]
348
349 =over 4
350
351 =item *
352
353 The C<PL_statbuf> interpreter variable has been removed.
354
355 =back
356
357 =head1 Selected Bug Fixes
358
359 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
360 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
361
362 [ List each fix as a =item entry ]
363
364 =over 4
365
366 =item *
367
368 XXX
369
370 =back
371
372 =head1 Known Problems
373
374 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
375 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
376 platform specific bugs also go here.
377
378 [ List each fix as a =item entry ]
379
380 =over 4
381
382 =item *
383
384 XXX
385
386 =back
387
388 =head1 Errata From Previous Releases
389
390 =over 4
391
392 =item *
393
394 XXX Add anything here that we forgot to add, or were mistaken about, in
395 the perldelta of a previous release.
396
397 =back
398
399 =head1 Obituary
400
401 XXX If any significant core contributor has died, we've added a short obituary
402 here.
403
404 =head1 Acknowledgements
405
406 XXX Generate this with:
407
408   perl Porting/acknowledgements.pl v5.25.5..HEAD
409
410 =head1 Reporting Bugs
411
412 If you find what you think is a bug, you might check the perl bug database
413 at L<https://rt.perl.org/> .  There may also be information at
414 L<http://www.perl.org/> , the Perl Home Page.
415
416 If you believe you have an unreported bug, please run the L<perlbug> program
417 included with your release.  Be sure to trim your bug down to a tiny but
418 sufficient test case.  Your bug report, along with the output of C<perl -V>,
419 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
420
421 If the bug you are reporting has security implications which make it
422 inappropriate to send to a publicly archived mailing list, then see
423 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
424 for details of how to report the issue.
425
426 =head1 Give Thanks
427
428 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
429 you can do so by running the C<perlthanks> program:
430
431     perlthanks
432
433 This will send an email to the Perl 5 Porters list with your show of thanks.
434
435 =head1 SEE ALSO
436
437 The F<Changes> file for an explanation of how to view exhaustive details on
438 what changed.
439
440 The F<INSTALL> file for how to build Perl.
441
442 The F<README> file for general stuff.
443
444 The F<Artistic> and F<Copying> files for copyright information.
445
446 =cut