Porting/how_to_write_a_perldelta.pod

   1 =head1 How to write a perldelta
   2
   3 This is intended as a guide for how to write a perldelta. There has never
   4 been a formal specification - the working rule is "fake up a document that
   5 looks something close to the existing perldeltas". So if it's unclear how
   6 do to do something, see if it's been done before, and if the approach works
   7 there, steal it.
   8
   9 =head2 Template
  10
  11 Note there is a file F<Porting/perldelta_template> which contains a
  12 skeleton version of a perldelta.pod file, which should normally be copied
  13 in at the start of a new release.
  14
  15 =head2 Style
  16
  17 Pod is more a physical markup language, rather than a logical markup language.
  18 Despite that it has some built in conventions. B<Stick to them>:
  19
  20 =over 4
  21
  22 =item * C<FE<lt>E<gt>> is for File
  23
  24 =item * C<CE<lt>E<gt>> is for Code
  25
  26 =item * C<LE<lt>E<gt>> is for Link
  27
  28 =back
  29
  30 Whilst modules could also be links, usually in the context of the perldelta
  31 the reference is to code C<use>ing them, rather than something within their
  32 documentation.
  33
  34 Be consistent in how bugs are referenced. One style is
  35
  36 =over 4
  37
  38 =item rt.perl.org
  39
  40 C<RT #43010> inline, but enclose in square brackets after a sentence.
  41 C<[RT #43010]>
  42
  43 =item ActiveState
  44
  45 C<http://bugs.activestate.com/show_bug.cgi?id=72443>
  46
  47 =item Debian
  48
  49 C<Debian bug #379463>
  50
  51 =back
  52
  53 =head2 Copy editing
  54
  55 Be consistent.
  56
  57 In a list, either make every item a note, or a full sentence. Either end
  58 every item with a full stop, or ensure that no item ends with one. I<regex>
  59 B<xor> I<regexp> - choose exactly one, and stick to it.
  60
  61 =head2 Sections
  62
  63 Historically, the perldelta has consisted of a sequence of C<=head1>
  64 sections, usually in the same order. Un-needed sections are deleted,
  65 and if something doesn't fit nicely into the existing sections, a new
  66 more appropriate section is created.
  67
  68 =over
  69
  70 =item NAME
  71
  72 Follows this formula:
  73
  74     perl5104delta - what is new for perl v5.10.4
  75
  76 =item DESCRIPTION
  77
  78 For a release on a stable branch, follows this formula:
  79
  80     This document describes differences between the 5.10.3 release and
  81     the 5.10.4 release.
  82
  83 For the start of a new stable branch, follows this formula:
  84
  85     This document describes differences between the 5.12.0 release and
  86     the 5.10.0 release.
  87
  88 Clearly this sets the scope of which changes are to be summarised in the rest
  89 of the document.
  90
  91 =item Notice
  92
  93 There was a I<Notice> section in L<perl589delta>, to carry an important
  94 notice.
  95
  96 =item Incompatible Changes
  97
  98 For a release on a stable branch, this section aspires to be
  99
 100     There are no changes intentionally incompatible with 5.10.3. If any exist,
 101     they are bugs and reports are welcome.
 102
 103 =item Core Enhancements
 104
 105 New core language features go here. Summarise user-visible core language
 106 enhancements. Particularly prominent performance optimisations could go
 107 here, but most should go in the L</Performance Enhancements> section.
 108
 109 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
 110
 111 =item New Platforms
 112
 113 List any platforms that this version of perl compiles on, that previous
 114 versions did not. These will either be enabled by new files in the F<hints/>
 115 directories, or new subdirectories and F<README> files at the top level of the
 116 source tree.
 117
 118 =item Modules and Pragmata
 119
 120 All changes to installed files in F<ext/> and F<lib/> go here, in a list
 121 ordered by distribution name. Minimally it should be the module version,
 122 but it's more useful to the end user to give a paragraph's summary of the
 123 module's changes. In an ideal world, dual-life modules would have a
 124 F<Changes> file that could be cribbed.
 125
 126 Whilst this section could be built by incrementally working through change
 127 descriptions applying to files, this is prone to error. It's better to
 128 collate changes to F<ext/> and F<lib/> by module, and then summarise all
 129 changes to a module as a group. This can be done by partitioning directories
 130 within F<ext/> and F<lib/> to a number of people.
 131
 132 B<FIXME> - this could be automated, although the two below would be easier
 133 to start with.
 134
 135 Start with F<Porting/cmpVERSION.pl>
 136
 137 Augment it with a flag, so that instead of reporting which modules are
 138 different but have the same version, report on modules which I<are> different.
 139 Grab the old version from the exploded tarball, and the new version from
 140 the git checkout, and output the line
 141
 142     =item *
 143
 144     C<less> upgraded from version 0.01 to 0.02
 145
 146 That's a start.
 147
 148 Once that's done, a more adventurous enhancement is to automate grabbing
 149 the changelogs for dual lived modules. For each of them, grab the relevant
 150 changes files from CPAN for the old and new versions, and if the old one is
 151 a strict subset of the new one, splice the extra lines right into the output,
 152 as a basis for summarising.
 153
 154 (And if not, experiment with using F<git> to get the relevant part of changelog
 155 for the particular file in core)
 156
 157 These could also be enhanced further by using a Pod parser module to produce
 158 a parse tree of F<perl${whatever}delta.pod>, and splicing in the updates
 159 correctly without throwing existing entries away.
 160
 161 If you think that's nuts, take a look at what F<pod/buildtoc> already does to
 162 splice into existing Makefiles on various platforms:
 163
 164 http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498
 165
 166 Perl is this really powerful language for text manipulation. And fun to
 167 play with. We need to get that message out. :-)
 168
 169 =item Utility Changes
 170
 171 Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
 172 of these are built within the directories F<utils> and F<x2p>.
 173
 174 =item New Documentation
 175
 176 Changes which create B<new> files in F<pod/> go here.
 177
 178 B<FIXME> - this could be automated, at least as far as generating a first
 179 draft.
 180
 181 =over
 182
 183 =item 1
 184
 185 Start with a clean exploded tarball of the previous release, and a clean
 186 checkout of the branch in question
 187
 188 =item 2
 189
 190 Take the F<MANIFEST> file of each
 191
 192 =item 3
 193
 194 Search for lines matching C<m!^pod/.*\.pod!>
 195
 196 =item 4
 197
 198 Diff them
 199
 200 =item 5
 201
 202 Explode if anyone deleted documentation. [No idea what the policy on that is
 203 yet]
 204
 205 =item 6
 206
 207 For each file only in the newer F<MANIFEST>
 208
 209 =over
 210
 211 =item 1
 212
 213 Use F<git> to determine its Author
 214
 215 =item 2
 216
 217 Open the pod file itself
 218
 219 =item 3
 220
 221 Grab the description section
 222
 223 =item 4
 224
 225 Write out a block of text starting roughly
 226
 227     L<perlfoo>, by A. U. Thor, provides @description
 228
 229 =back
 230
 231 =back
 232
 233 =item Changes to Existing Documentation
 234
 235 Changes which significantly change existing files in F<pod/> go here.
 236 Any changes to F<pod/perldiag.pod> should go in
 237 L</New or Changed Diagnostics>.
 238
 239 =item Performance Enhancements
 240
 241 Changes which enhance performance without changing behaviour go here. There
 242 may well be none in a stable release.
 243
 244 =item Installation and Configuration Improvements
 245
 246 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 247 go here.
 248
 249 =item Selected Bug Fixes
 250
 251 Important bug fixes in the core language are summarised here.
 252 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
 253 L</Modules and Pragmata>.
 254
 255 =item New or Changed Diagnostics
 256
 257 New or changed warnings emitted by the core's C<C> code go here.
 258
 259 =item Changed Internals
 260
 261 Changes which affect the interface available to C<XS> code go here.
 262
 263 =item New Tests
 264
 265 Changes which create B<new> files in F<t/> go here. Changes to existing files
 266 in F<t/> aren't worth summarising, although the bugs that they represent
 267 may be.
 268
 269 B<FIXME> - this could be automated, at least as far as generating a first
 270 draft.
 271
 272 =over
 273
 274 =item 1
 275
 276 Start with a clean exploded tarball of the previous release, and a clean
 277 checkout of the branch in question
 278
 279 =item 2
 280
 281 Take the F<MANIFEST> file of each
 282
 283 =item 3
 284
 285 Search for lines matching C<m!t/.*\.t!> (and I think also for new tests in
 286 F<ext/DynaLoader>)
 287
 288 =item 4
 289
 290 Diff them
 291
 292 =item 5
 293
 294 For each file only in the newer F<MANIFEST>
 295
 296 =over
 297
 298 =item 1
 299
 300 Grab the description line from F<MANIFEST>
 301
 302 =item 2
 303
 304 Write out an =item section with the filename, and description, just like
 305 L<http://perl5.git.perl.org/perl.git/blob/maint-5.10:/pod/perl5101delta.pod>
 306
 307 =back
 308
 309 =back
 310
 311 =item Known Problems
 312
 313 Descriptions of platform agnostic bugs we know we can't fix go here. Any
 314 tests that had to be C<TODO>ed for the release would be noted here, unless
 315 they were specific to a particular platform (see below).
 316
 317 =item Deprecations
 318
 319 Add any new known deprecations here.
 320
 321 =item Platform Specific Notes
 322
 323 Any changes specific to a particular platform. VMS and Win32 are the usual
 324 stars here. It's probably best to group changes under the same section layout
 325 as the main perldelta.
 326
 327 =item Obituary
 328
 329 If any significant core contributor has died, we've added a short obituary
 330 here.
 331
 332 =item Acknowledgements
 333
 334 The list of people to thank goes here.
 335
 336 =item Reporting Bugs
 337
 338 This doesn't usually need to be changed from the previous perldelta.
 339
 340 =item SEE ALSO
 341
 342 This doesn't usually need to be changed from the previous perldelta.
 343
 344 =back