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