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 Style
  10
  11 Pod is more a physical markup language, rather than a logical markup language.
  12 Despite that it has some built in conventions. B<Stick to them>:
  13
  14 =over 4
  15
  16 =item * C<FE<lt>E<gt>> is for File
  17
  18 =item * C<CE<lt>E<gt>> is for Code
  19
  20 =item * C<LE<lt>E<gt>> is for Link
  21
  22 =back
  23
  24 Whilst modules could also be links, usually in the context of the perldelta
  25 the reference is to code C<use>ing them, rather than something within their
  26 documentation.
  27
  28 Be consistent in how bugs are referenced. One style is
  29
  30 =over 4
  31
  32 =item rt.perl.org
  33
  34 C<RT #43010> inline, but enclose in square brackets after a sentence.
  35 C<[RT #43010]>
  36
  37 =item ActiveState
  38
  39 C<http://bugs.activestate.com/show_bug.cgi?id=72443>
  40
  41 =item Debian
  42
  43 C<Debian bug #379463>
  44
  45 =back
  46
  47 =head2 Copy editing
  48
  49 Be consistent.
  50
  51 In a list, either make every item a note, or a full sentence. Either end
  52 every item with a full stop, or ensure that no item ends with one. I<regex>
  53 B<xor> I<regexp> - choose exactly one, and stick to it.
  54
  55 =head2 Sections
  56
  57 Historically, the perldelta has consisted of a sequence of C<=head1>
  58 sections, usually in the same order. Un-needed sections are deleted,
  59 and if something doesn't fit nicely into the existing sections, a new
  60 more appropriate section is created.
  61
  62 =over
  63
  64 =item NAME
  65
  66 Follows this formula:
  67
  68     perl5104delta - what is new for perl v5.10.4
  69
  70 =item DESCRIPTION
  71
  72 For a release on a stable branch, follows this formula:
  73
  74     This document describes differences between the 5.10.3 release and
  75     the 5.10.4 release.
  76
  77 For the start of a new stable branch, follows this formula:
  78
  79     This document describes differences between the 5.12.0 release and
  80     the 5.10.0 release.
  81
  82 Clearly this sets the scope of which changes are to be summarised in the rest
  83 of the document.
  84
  85 =item Notice
  86
  87 There was a I<Notice> section in L<perl589delta>, to carry an important
  88 notice.
  89
  90 =item Incompatible Changes
  91
  92 For a release on a stable branch, this section aspires to be
  93
  94     There are no changes intentionally incompatible with 5.10.3. If any exist,
  95     they are bugs and reports are welcome.
  96
  97 =item Core Enhancements
  98
  99 New core language features go here. Summarise user-visible core language
 100 enhancements. Particularly prominent performance optimisations could go
 101 here, but most should go in the L</Performance Enhancements> section.
 102
 103 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
 104
 105 =item New Platforms
 106
 107 List any platforms that this version of perl compiles on, that previous
 108 versions did not. These will either be enabled by new files in the F<hints/>
 109 directories, or new subdirectories and F<README> files at the top level of the
 110 source tree.
 111
 112 =item Modules and Pragmata
 113
 114 All changes to installed files in F<ext/> and F<lib/> go here, in a list
 115 ordered by distribution name. Minimally it should be the module version,
 116 but it's more useful to the end user to give a paragraph's summary of the
 117 module's changes. In an ideal world, dual-life modules would have a
 118 F<Changes> file that could be cribbed.
 119
 120 Whilst this section could be built by incrementally working through change
 121 descriptions applying to files, this is prone to error. It's better to
 122 collate changes to F<ext/> and F<lib/> by module, and then summarise all
 123 changes to a module as a group. This can be done by partitioning directories
 124 within F<ext/> and F<lib/> to a number of people.
 125
 126 =item Utility Changes
 127
 128 Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
 129 of these are built within the directories F<utils> and F<x2p>.
 130
 131 =item New Documentation
 132
 133 Changes which create B<new> files in F<pod/> go here.
 134
 135 =item Changes to Existing Documentation
 136
 137 Changes which significantly change existing files in F<pod/> go here.
 138 Any changes to F<pod/perldiag.pod> should go in
 139 L</New or Changed Diagnostics>.
 140
 141 =item Performance Enhancements
 142
 143 Changes which enhance performance without changing behaviour go here. There
 144 may well be none in a stable release.
 145
 146 =item Installation and Configuration Improvements
 147
 148 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 149 go here.
 150
 151 =item Selected Bug Fixes
 152
 153 Important bug fixes in the core language are summarised here.
 154 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
 155 L</Modules and Pragmata>.
 156
 157 =item New or Changed Diagnostics
 158
 159 New or changed warnings emitted by the core's C<C> code go here.
 160
 161 =item Changed Internals
 162
 163 Changes which affect the interface available to C<XS> code go here.
 164
 165 =item New Tests
 166
 167 Changes which create B<new> files in F<t/> go here. Changes to existing files
 168 in F<t/> aren't worth summarising, although the bugs that they represent
 169 may be.
 170
 171 =item Known Problems
 172
 173 Descriptions of platform agnostic bugs we know we can't fix go here. Any
 174 tests that had to be C<TODO>ed for the release would be noted here, unless
 175 they were specific to a particular platform (see below).
 176
 177 =item Deprecations
 178
 179 Add any new known deprecations here.
 180
 181 =item Platform Specific Notes
 182
 183 Any changes specific to a particular platform. VMS and Win32 are the usual
 184 stars here. It's probably best to group changes under the same section layout
 185 as the main perldelta.
 186
 187 =item Obituary
 188
 189 If any significant core contributor has died, we've added a short obituary
 190 here.
 191
 192 =item Acknowledgements
 193
 194 The list of people to thank goes here.
 195
 196 =item Reporting Bugs
 197
 198 This doesn't usually need to be changed from the previous perldelta.
 199
 200 =item SEE ALSO
 201
 202 This doesn't usually need to be changed from the previous perldelta.
 203
 204 =back