Porting/how_to_write_a_perldelta.pod

   1 =head1 NAME
   2
   3 how_to_write_a_perldelta - How to write a perldelta
   4
   5 =head2 Description
   6
   7 This is intended as a guide for how to write a perldelta. There has never
   8 been a formal specification - the working rule is "fake up a document that
   9 looks something close to the existing perldeltas". So if it's unclear how
  10 to do something, see if it's been done before, and if the approach works
  11 there, steal it. (L<perl5300delta> and L<perl5320delta> are both quite
  12 lengthy and contain good examples for many of the perldelta sections.)
  13
  14 =head2 Template Automation
  15
  16 Note that F<Porting/perldelta_template.pod> contains a skeleton version of
  17 a perldelta.pod file. Following the steps in the Release Manager's Guide
  18 (F<Porting/release_managers_guide.pod>) usually ensures hassle-free
  19 rotation of the most recently completed perldelta.pod and preparation of
  20 a fresh new document ready for the next release.
  21
  22 The skeleton document also contains inline hints on how to prepare the
  23 final perldelta.pod. (These hints should be removed in turn as each section
  24 of the final perldelta.pod is completed.)
  25
  26 =head2 Style
  27
  28 Pod is more a physical markup language, rather than a logical markup language.
  29 Despite that it has some built in conventions. B<Stick to them>:
  30
  31 =over 4
  32
  33 =item * C<FE<lt>E<gt>> is for File
  34
  35 =item * C<CE<lt>E<gt>> is for Code
  36
  37 =item * C<LE<lt>E<gt>> is for Link
  38
  39 =back
  40
  41 Whilst modules could also be links, usually in the context of the perldelta
  42 the reference is to code C<use>ing them, rather than something within their
  43 documentation.
  44
  45 Be consistent in how bugs are referenced. One style is
  46
  47 =over 4
  48
  49 =item GitHub
  50
  51 C<[GH #12345]> can be used to reference both Issues and Pull Requests.
  52
  53 =item rt.cpan.org
  54
  55 C<rt.cpan.org #43010> inline, but enclose in square brackets after a sentence.
  56 C<[rt.cpan.org #43010]>.  This mirrors how rt.cpan.org subject lines appear.
  57
  58 =item ActiveState
  59
  60 C<L<http://bugs.activestate.com/show_bug.cgi?id=72443>>
  61
  62 =item Debian
  63
  64 C<Debian bug #379463>
  65
  66 =back
  67
  68 =head2 Copy editing
  69
  70 Be consistent.
  71
  72 In a list, either make every item a note, or a full sentence. Either end
  73 every item with a full stop, or ensure that no item ends with one. I<regex>
  74 B<xor> I<regexp> - choose exactly one, and stick to it.
  75
  76 =head2 Sections
  77
  78 Historically, the perldelta has consisted of a sequence of C<=head1>
  79 sections, usually in the same order. Un-needed sections are deleted,
  80 and if something doesn't fit nicely into the existing sections, a new
  81 more appropriate section is created.
  82
  83 =over
  84
  85 =item NAME
  86
  87 Follows this formula:
  88
  89     perl5104delta - what is new for perl v5.10.4
  90
  91 =item DESCRIPTION
  92
  93 For a release on a stable branch, follows this formula:
  94
  95     This document describes differences between the 5.10.3 release
  96     and the 5.10.4 release.
  97
  98 For the start of a new stable branch, follows this formula:
  99
 100     This document describes differences between the 5.10.0 release
 101     and the 5.12.0 release.
 102
 103 This clearly sets the scope of which changes are to be summarized in the
 104 rest of the document.
 105
 106 For all releases, a second paragraph points to the previous perldelta:
 107
 108     If you are upgrading from an earlier release such as 5.rXXX.aXXX,
 109     first read perl5XXXdelta, which describes differences between
 110     5.rXXX.aXXX and 5.sXXX.bXXX.
 111
 112 =item Notice
 113
 114 There was a I<Notice> section in L<perl589delta>, to carry an important
 115 notice.
 116
 117 =item Core Enhancements
 118
 119 New core language features go here. Summarize user-visible core language
 120 enhancements. Particularly prominent performance optimisations could go
 121 here, but most should go in the L</Performance Enhancements> section.
 122
 123 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
 124
 125 =item Security
 126
 127 Any security-related notices go here. In particular, any security
 128 vulnerabilities closed should be noted here rather than in the
 129 "Selected Bug Fixes" section.
 130
 131 L<perl5303delta> has multiple such examples, as well as
 132 a useful accompanying paragraph outlining the known attack
 133 vectors / requirements for the vulnerabilities to be exploitable.
 134
 135 =item Incompatible Changes
 136
 137 For a release on a stable branch, this section aspires to be
 138
 139     There are no changes intentionally incompatible with 5.10.3.
 140     If any exist, they are bugs and reports are welcome.
 141
 142 Otherwise, changes should be listed as =head2 entries.
 143
 144 =item Deprecations
 145
 146 Add any new known deprecations (features, syntax, modules) here.
 147
 148 A I<Module removals> subsection can be used to foreshadow planned removal
 149 of core modules in a future release. Modules that were actually removed
 150 in this release should go in the "Modules and Pragmata" section.
 151
 152 =item Performance Enhancements
 153
 154 Changes which enhance performance without changing behaviour go here. There
 155 may well be none in a stable release.
 156
 157 =item Modules and Pragmata
 158
 159 All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/> go
 160 here, in a list ordered by distribution name. Minimally it should be the
 161 module version, but it's more useful to the end user to give a paragraph's
 162 summary of the module's changes. In an ideal world, dual-life modules would
 163 have a F<Changes> file that could be cribbed.
 164
 165 Whilst this section could be built by incrementally working through change
 166 descriptions applying to files, this is prone to error. It's better to
 167 collate changes by module, and then summarize all changes to a module as a
 168 group.
 169
 170 If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
 171 will automatically update two sections in F<perldelta>:
 172
 173     * New Modules and Pragmata
 174     * Updated Modules and Pragmata
 175     * Removed Modules and Pragmata
 176
 177 Each section will have stub entries following a template like this:
 178
 179     =item C<less>
 180
 181     Upgraded from version 0.01 to 0.02
 182
 183 It does not include modules listed in F<Porting/Maintainers.pl> under
 184 C<_PERLLIB>, but it's a start.  Where relevant, a summary of changes can be
 185 added by hand.
 186
 187 A more adventurous enhancement would be to automate grabbing
 188 the changelogs for dual lived modules. For each of them, grab the relevant
 189 changes files from CPAN for the old and new versions, and if the old one is
 190 a strict subset of the new one, use the extra lines as a basis for summarizing.
 191
 192 (And if not, experiment with using F<git> to get the relevant part of changelog
 193 for the particular file in core.)
 194
 195 =item New Documentation
 196
 197 Changes which create B<new> files in F<pod/> go here.
 198
 199 B<FIXME> - this could be automated, at least as far as generating a first
 200 draft.
 201
 202 =over
 203
 204 =item 1
 205
 206 Start with a clean exploded tarball of the previous release, and a clean
 207 checkout of the branch in question
 208
 209 =item 2
 210
 211 Take the F<MANIFEST> file of each
 212
 213 =item 3
 214
 215 Search for lines matching C<m!^pod/.*\.pod!>
 216
 217 =item 4
 218
 219 Diff them
 220
 221 =item 5
 222
 223 Explode if anyone deleted documentation. [No idea what the policy on that is
 224 yet]
 225
 226 =item 6
 227
 228 For each file only in the newer F<MANIFEST>
 229
 230 =over
 231
 232 =item 1
 233
 234 Use F<git> to determine its Author
 235
 236 =item 2
 237
 238 Open the pod file itself
 239
 240 =item 3
 241
 242 Grab the description section
 243
 244 =item 4
 245
 246 Write out a block of text starting roughly
 247
 248     L<perlfoo>, by A. U. Thor, provides @description
 249
 250 =back
 251
 252 =back
 253
 254 =item Changes to Existing Documentation
 255
 256 Changes which significantly change existing files in F<pod/> go here.
 257 Any changes to F<pod/perldiag.pod> should go in
 258 L</New Diagnostics> or L</Changed Diagnostics>.
 259
 260 =item New Diagnostics
 261
 262 New warnings emitted by the core's C<C> code go here.
 263
 264 =item Changed Diagnostics
 265
 266 Changed warnings emitted by the core's C<C> code go here.
 267
 268 =item Utility Changes
 269
 270 Changes to installed programs such as F<perldoc> and F<xsubpp> go here. Most
 271 of these are built within the directory F<utils>.
 272
 273 =item Configuration and Compilation
 274
 275 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 276 go here.
 277
 278 =item Testing
 279
 280 Changes which create B<new> files in F<t/> go here. Changes to existing files
 281 in F<t/> aren't worth summarizing, although the bugs that they represent
 282 may be.
 283
 284 Autogenerate this section by running something like this:
 285
 286  # perl newtests-perldelta.pl v5.11.1 HEAD
 287
 288 =item Platform Support
 289
 290 Any changes specific to a particular platform. VMS and Win32 are the usual
 291 stars here. It's probably best to group changes under the same section layout
 292 as the main perldelta.
 293
 294 =item New Platforms
 295
 296 List any platforms that this version of perl compiles on, that previous
 297 versions did not. These will either be enabled by new files in the F<hints/>
 298 directories, or new subdirectories and F<README> files at the top level of the
 299 source tree.
 300
 301 =item Discontinued Platforms
 302
 303 List any platforms that this version of perl no longer compiles on. The
 304 reverse of the advice above applies - look for removed hints or README files.
 305
 306 =item Platform-Specific Notes
 307
 308 Changes of note to specific platforms go here.
 309
 310 =item Internal Changes
 311
 312 Changes which affect the interface available to C<XS> code go here.
 313
 314 =item Selected Bug Fixes
 315
 316 Important bug fixes in the core language are summarized here.
 317 Bug fixes in files in F<ext/> and F<lib/> are best summarized in
 318 L</Modules and Pragmata>.
 319
 320 =item Known Problems
 321
 322 Descriptions of platform agnostic bugs we know we can't fix go here. Any
 323 tests that had to be C<TODO>ed for the release would be noted here, unless
 324 they were specific to a particular platform (see below).
 325
 326 =item Errata From Previous Releases
 327
 328 XXXXXXXXXX TODO
 329
 330 =item Obituary
 331
 332 If any significant core contributor has died, we've added a short obituary
 333 here.
 334
 335 =item Acknowledgements
 336
 337 Generate this with:
 338
 339   perl Porting/acknowledgements.pl v5.15.0..HEAD
 340
 341 =item Reporting Bugs
 342
 343 This doesn't usually need to be changed from the previous perldelta.
 344
 345 =item Give Thanks
 346
 347 This doesn't usually need to be changed from the previous perldelta.
 348
 349 =item SEE ALSO
 350
 351 This doesn't usually need to be changed from the previous perldelta.
 352
 353 =back