| 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 |