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