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 L<perl5XXXdelta>, which describes differences between 5.XXX.XXX and
  15 5.XXX.XXX.
  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.  If Module::CoreList is updated, generate an initial draft of the
  46 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
  47 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
  48 below.  A paragraph summary for important changes should then be added by hand.
  49 In an ideal world, dual-life modules would have a F<Changes> file that could be
  50 cribbed.
  51
  52 =head2 New Modules and Pragmata
  53
  54 =head2 Pragmata Changes
  55
  56 =head2 Updated Modules
  57
  58 =head2 Removed Modules and Pragmata
  59
  60 =head1 Utility Changes
  61
  62 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
  63 here. Most of these are built within the directories F<utils> and F<x2p>.
  64
  65 =over 4
  66
  67 =item F<XXX>
  68
  69 XXX
  70
  71 =back
  72
  73 =head1 New Documentation
  74
  75 XXX Changes which create B<new> files in F<pod/> go here.
  76
  77 =over 4
  78
  79 =item L<XXX>
  80
  81 XXX
  82
  83 =back
  84
  85 =head1 Changes to Existing Documentation
  86
  87 XXX Changes which significantly change existing files in F<pod/> go here.
  88 Any changes to F<pod/perldiag.pod> should go in L</New or Changed Diagnostics>.
  89
  90
  91 =head1 Performance Enhancements
  92
  93 XXX Changes which enhance performance without changing behaviour go here. There
  94 may well be none in a stable release.
  95
  96 =over 4
  97
  98 =item *
  99
 100 XXX
 101
 102 =back
 103
 104 =head1 Installation and Configuration Improvements
 105
 106 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 107 go here.
 108
 109 =head2 Configuration improvements
 110
 111 XXX
 112
 113 =head2 Compilation improvements
 114
 115 XXX
 116
 117 =head2 Platform Specific Changes
 118
 119 =over 4
 120
 121 =item XXX-some-platform
 122
 123 XXX
 124
 125 =back
 126
 127 =head1 Selected Bug Fixes
 128
 129 XXX Important bug fixes in the core language are summarised here.
 130 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
 131 L</Modules and Pragmata>.
 132
 133 =over 4
 134
 135 =item *
 136
 137 XXX
 138
 139 =back
 140
 141 =head1 New or Changed Diagnostics
 142
 143 XXX New or changed warnings emitted by the core's C<C> code go here.
 144
 145 =over 4
 146
 147 =item C<XXX>
 148
 149 XXX
 150
 151 =back
 152
 153 =head1 Changed Internals
 154
 155 XXX Changes which affect the interface available to C<XS> code go here.
 156
 157 =over 4
 158
 159 =item *
 160
 161 XXX
 162
 163 =back
 164
 165 =head1 New Tests
 166
 167 XXX Changes which create B<new> files in F<t/> go here. Changes to
 168 existing files in F<t/> aren't worth summarising, although the bugs that
 169 they represent may be.
 170
 171 =over 4
 172
 173 =item F<XXX>
 174
 175 XXX
 176
 177 =back
 178
 179 =head1 Known Problems
 180
 181 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
 182 tests that had to be C<TODO>ed for the release would be noted here, unless
 183 they were specific to a particular platform (see below).
 184
 185 This is a list of some significant unfixed bugs, which are regressions
 186 from either 5.XXX.XXX or 5.XXX.XXX.
 187
 188 =over 4
 189
 190 =item *
 191
 192 XXX
 193
 194 =back
 195
 196 =head1 Deprecations
 197
 198 XXX Add any new known deprecations here.
 199
 200 The following items are now deprecated.
 201
 202 =over 4
 203
 204 =item *
 205
 206 XXX
 207
 208 =back
 209
 210 =head1 Platform Specific Notes
 211
 212 XXX Any changes specific to a particular platform. VMS and Win32 are the usual
 213 stars here. It's probably best to group changes under the same section layout
 214 as the main perldelta
 215
 216 =head1 Obituary
 217
 218 XXX If any significant core contributor has died, we've added a short obituary
 219 here.
 220
 221 =head1 Acknowledgements
 222
 223 XXX The list of people to thank goes here.
 224
 225
 226 =head1 Reporting Bugs
 227
 228 If you find what you think is a bug, you might check the articles
 229 recently posted to the comp.lang.perl.misc newsgroup and the perl
 230 bug database at http://rt.perl.org/perlbug/ .  There may also be
 231 information at http://www.perl.org/ , the Perl Home Page.
 232
 233 If you believe you have an unreported bug, please run the B<perlbug>
 234 program included with your release.  Be sure to trim your bug down
 235 to a tiny but sufficient test case.  Your bug report, along with the
 236 output of C<perl -V>, will be sent off to perlbug@perl.org to be
 237 analysed by the Perl porting team.
 238
 239 If the bug you are reporting has security implications, which make it
 240 inappropriate to send to a publicly archived mailing list, then please send
 241 it to perl5-security-report@perl.org. This points to a closed subscription
 242 unarchived mailing list, which includes all the core committers, who be able
 243 to help assess the impact of issues, figure out a resolution, and help
 244 co-ordinate the release of patches to mitigate or fix the problem across all
 245 platforms on which Perl is supported. Please only use this address for
 246 security issues in the Perl core, not for modules independently
 247 distributed on CPAN.
 248
 249 =head1 SEE ALSO
 250
 251 The F<Changes> file for an explanation of how to view exhaustive details
 252 on what changed.
 253
 254 The F<INSTALL> file for how to build Perl.
 255
 256 The F<README> file for general stuff.
 257
 258 The F<Artistic> and F<Copying> files for copyright information.
 259
 260 =cut