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