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 better
 133
 134 If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
 135 will automatically print out several sections if relevent that can be
 136 pasted into F<perldelta>:
 137
 138     * New Modules and Pragmata
 139     * Pragmata Changes
 140     * Updated Modules
 141     * Removed Modules and Pragmata
 142
 143 Each section will have stub entries following a template like this:
 144
 145     =item C<less>
 146
 147     Upgraded from version 0.01 to 0.02
 148
 149 It does not include modules listed in F<Porting/Maintainers.pl> under
 150 C<_PERLLIB>, but it's a start.  Where relevent, a summary of changes can be
 151 added by hand.
 152
 153 A more adventurous enhancement would be to automate grabbing
 154 the changelogs for dual lived modules. For each of them, grab the relevant
 155 changes files from CPAN for the old and new versions, and if the old one is
 156 a strict subset of the new one, splice the extra lines right into the output,
 157 as a basis for summarising.
 158
 159 (And if not, experiment with using F<git> to get the relevant part of changelog
 160 for the particular file in core)
 161
 162 These could also be enhanced further by using a Pod parser module to produce
 163 a parse tree of F<perl${whatever}delta.pod>, and splicing in the updates
 164 correctly without throwing existing entries away.
 165
 166 If you think that's nuts, take a look at what F<pod/buildtoc> already does to
 167 splice into existing Makefiles on various platforms:
 168
 169 http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498
 170
 171 Perl is this really powerful language for text manipulation. And fun to
 172 play with. We need to get that message out. :-)
 173
 174 =item Utility Changes
 175
 176 Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
 177 of these are built within the directories F<utils> and F<x2p>.
 178
 179 =item New Documentation
 180
 181 Changes which create B<new> files in F<pod/> go here.
 182
 183 B<FIXME> - this could be automated, at least as far as generating a first
 184 draft.
 185
 186 =over
 187
 188 =item 1
 189
 190 Start with a clean exploded tarball of the previous release, and a clean
 191 checkout of the branch in question
 192
 193 =item 2
 194
 195 Take the F<MANIFEST> file of each
 196
 197 =item 3
 198
 199 Search for lines matching C<m!^pod/.*\.pod!>
 200
 201 =item 4
 202
 203 Diff them
 204
 205 =item 5
 206
 207 Explode if anyone deleted documentation. [No idea what the policy on that is
 208 yet]
 209
 210 =item 6
 211
 212 For each file only in the newer F<MANIFEST>
 213
 214 =over
 215
 216 =item 1
 217
 218 Use F<git> to determine its Author
 219
 220 =item 2
 221
 222 Open the pod file itself
 223
 224 =item 3
 225
 226 Grab the description section
 227
 228 =item 4
 229
 230 Write out a block of text starting roughly
 231
 232     L<perlfoo>, by A. U. Thor, provides @description
 233
 234 =back
 235
 236 =back
 237
 238 =item Changes to Existing Documentation
 239
 240 Changes which significantly change existing files in F<pod/> go here.
 241 Any changes to F<pod/perldiag.pod> should go in
 242 L</New or Changed Diagnostics>.
 243
 244 =item Performance Enhancements
 245
 246 Changes which enhance performance without changing behaviour go here. There
 247 may well be none in a stable release.
 248
 249 =item Installation and Configuration Improvements
 250
 251 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 252 go here.
 253
 254 =item Selected Bug Fixes
 255
 256 Important bug fixes in the core language are summarised here.
 257 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
 258 L</Modules and Pragmata>.
 259
 260 =item New or Changed Diagnostics
 261
 262 New or changed warnings emitted by the core's C<C> code go here.
 263
 264 =item Changed Internals
 265
 266 Changes which affect the interface available to C<XS> code go here.
 267
 268 =item New Tests
 269
 270 Changes which create B<new> files in F<t/> go here. Changes to existing files
 271 in F<t/> aren't worth summarising, although the bugs that they represent
 272 may be.
 273
 274 Autogenerate this section by running something like this:
 275
 276  # perl newtests-perldelta.pl v5.11.1 HEAD
 277
 278 =item Known Problems
 279
 280 Descriptions of platform agnostic bugs we know we can't fix go here. Any
 281 tests that had to be C<TODO>ed for the release would be noted here, unless
 282 they were specific to a particular platform (see below).
 283
 284 =item Deprecations
 285
 286 Add any new known deprecations here.
 287
 288 =item Platform Specific Notes
 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 Obituary
 295
 296 If any significant core contributor has died, we've added a short obituary
 297 here.
 298
 299 =item Acknowledgements
 300
 301 The list of people to thank goes here.
 302
 303 You can find the list of committers and authors by:
 304
 305   % git log v5.11.1..HEAD | perl -nlwe '$seen{$1}++ if /^Author: ([^<]*)/; END { print for sort keys %seen }'
 306
 307 And how many files where changed by:
 308
 309   % git diff v5.11.1..HEAD | diffstat
 310
 311 =item Reporting Bugs
 312
 313 This doesn't usually need to be changed from the previous perldelta.
 314
 315 =item SEE ALSO
 316
 317 This doesn't usually need to be changed from the previous perldelta.
 318
 319 =back