This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
mention Porting/corelist-perldelta.pl in perldelta instructions
[perl5.git] / Porting / perldelta_template.pod
1 =head1 NAME
2
3 [ this is a template for a new perldelta file. Any text flagged as
4 XXX needs to be processed before release. ]
5
6 perldelta - what is new for perl v5.XXX.XXX
7
8 =head1 DESCRIPTION
9
10 This document describes differences between the 5.XXX.XXX release and
11 the 5.XXX.XXX release.
12
13 If you are upgrading from an earlier release such as 5.XXX.XXX, first read
14 the L<perl5XXXdelta>, which describes differences between 5.XXX.XXX and
15 5.10.0
16
17 =head1 Notice
18
19 XXX Any important notices here
20
21 =head1 Incompatible Changes
22
23 XXX For a release on a stable branch, this section aspires to be:
24
25     There are no changes intentionally incompatible with 5.XXX.XXX. If any
26     exist, they are bugs and reports are welcome.
27
28
29 =head1 Core Enhancements
30
31 XXX New core language features go here. Summarise user-visible core language
32 enhancements. Particularly prominent performance optimisations could go
33 here, but most should go in the L</Performance Enhancements> section.
34
35 =head1 New Platforms
36
37 XXX List any platforms that this version of perl compiles on, that previous
38 versions did not. These will either be enabled by new files in the F<hints/>
39 directories, or new subdirectories and F<README> files at the top level of the
40 source tree.
41
42 =head1 Modules and Pragmata
43
44 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
45 go here, in a list ordered by distribution name. Minimally it should be the
46 module version, but it's more useful to the end user to give a paragraph's
47 summary of the module's changes. In an ideal world, dual-life modules would
48 have a F<Changes> file that could be cribbed.
49
50 =head2 New Modules and Pragmata
51
52 =over 4
53
54 =item C<XXX>
55
56 XXX
57
58 =back
59
60 =head2 Pragmata Changes
61
62 =over 4
63
64 =item C<XXX>
65
66 XXX
67
68 =back
69
70 =head2 Updated Modules
71
72 XXX If Module::CoreList is updated, generate this section using
73 F<Porting/corelist-perldelta.pl>
74
75 =over 4
76
77 =item C<XXX>
78
79 XXX
80
81 =back
82
83 =head1 Utility Changes
84
85 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
86 here. Most of these are built within the directories F<utils> and F<x2p>.
87
88 =over 4
89
90 =item F<XXX>
91
92 XXX
93
94 =back
95
96 =head1 New Documentation
97
98 XXX Changes which create B<new> files in F<pod/> go here.
99
100 =over 4
101
102 =item L<XXX>
103
104 XXX
105
106 =back
107
108 =head1 Changes to Existing Documentation
109
110 XXX Changes which significantly change existing files in F<pod/> go here.
111 Any changes to F<pod/perldiag.pod> should go in L</New or Changed Diagnostics>.
112
113
114 =head1 Performance Enhancements
115
116 XXX Changes which enhance performance without changing behaviour go here. There
117 may well be none in a stable release.
118
119 =over 4
120
121 =item *
122
123 XXX
124
125 =back
126
127 =head1 Installation and Configuration Improvements
128
129 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
130 go here.
131
132 =head2 Configuration improvements
133
134 XXX
135
136 =head2 Compilation improvements
137
138 XXX
139
140 =head2 Platform Specific Changes
141
142 =over 4
143
144 =item XXX-some-platform
145
146 XXX
147
148 =back
149
150 =head1 Selected Bug Fixes
151
152 XXX Important bug fixes in the core language are summarised here.
153 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
154 L</Modules and Pragmata>.
155
156 =over 4
157
158 =item *
159
160 XXX
161
162 =back
163
164 =head1 New or Changed Diagnostics
165
166 XXX New or changed warnings emitted by the core's C<C> code go here.
167
168 =over 4
169
170 =item C<XXX>
171
172 XXX
173
174 =back
175
176 =head1 Changed Internals
177
178 XXX Changes which affect the interface available to C<XS> code go here.
179
180 =over 4
181
182 =item *
183
184 XXX
185
186 =back
187
188 =head1 New Tests
189
190 XXX Changes which create B<new> files in F<t/> go here. Changes to
191 existing files in F<t/> aren't worth summarising, although the bugs that
192 they represent may be.
193
194 =over 4
195
196 =item F<XXX>
197
198 XXX
199
200 =back
201
202 =head1 Known Problems
203
204 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
205 tests that had to be C<TODO>ed for the release would be noted here, unless
206 they were specific to a particular platform (see below).
207
208 This is a list of some significant unfixed bugs, which are regressions
209 from either 5.XXX.XXX or 5.XXX.XXX.
210
211 =over 4
212
213 =item *
214
215 XXX
216
217 =back
218
219 =head1 Deprecations
220
221 XXX Add any new known deprecations here.
222
223 The following items are now deprecated.
224
225 =over 4
226
227 =item *
228
229 XXX
230
231 =back
232
233 =head1 Platform Specific Notes
234
235 XXX Any changes specific to a particular platform. VMS and Win32 are the usual
236 stars here. It's probably best to group changes under the same section layout
237 as the main perldelta
238
239 =head1 Obituary
240
241 XXX If any significant core contributor has died, we've added a short obituary
242 here.
243
244 =head1 Acknowledgements
245
246 XXX The list of people to thank goes here.
247
248
249 =head1 Reporting Bugs
250
251 If you find what you think is a bug, you might check the articles
252 recently posted to the comp.lang.perl.misc newsgroup and the perl
253 bug database at http://rt.perl.org/perlbug/ .  There may also be
254 information at http://www.perl.org/ , the Perl Home Page.
255
256 If you believe you have an unreported bug, please run the B<perlbug>
257 program included with your release.  Be sure to trim your bug down
258 to a tiny but sufficient test case.  Your bug report, along with the
259 output of C<perl -V>, will be sent off to perlbug@perl.org to be
260 analysed by the Perl porting team.
261
262 If the bug you are reporting has security implications, which make it
263 inappropriate to send to a publicly archived mailing list, then please send
264 it to perl5-security-report@perl.org. This points to a closed subscription
265 unarchived mailing list, which includes all the core committers, who be able
266 to help assess the impact of issues, figure out a resolution, and help
267 co-ordinate the release of patches to mitigate or fix the problem across all
268 platforms on which Perl is supported. Please only use this address for
269 security issues in the Perl core, not for modules independently
270 distributed on CPAN.
271
272 =head1 SEE ALSO
273
274 The F<Changes> file for an explanation of how to view exhaustive details
275 on what changed.
276
277 The F<INSTALL> file for how to build Perl.
278
279 The F<README> file for general stuff.
280
281 The F<Artistic> and F<Copying> files for copyright information.
282
283 =cut