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