From: Nicholas Clark Date: Mon, 14 Sep 2009 15:51:09 +0000 (+0100) Subject: Note how various parts of perldelta writing could be automated. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0be987a291dca2e27ebe17569a5442b14fcaa944;p=p5sagit%2Fp5-mst-13.2.git Note how various parts of perldelta writing could be automated. --- diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod index 53265bd..66f7adc 100644 --- a/Porting/how_to_write_a_perldelta.pod +++ b/Porting/how_to_write_a_perldelta.pod @@ -129,6 +129,43 @@ collate changes to F and F by module, and then summarise all changes to a module as a group. This can be done by partitioning directories within F and F to a number of people. +B - this could be automated, although the two below would be easier +to start with. + +Start with F + +Augment it with a flag, so that instead of reporting which modules are +different but have the same version, report on modules which I different. +Grab the old version from the exploded tarball, and the new version from +the git checkout, and output the line + + =item * + + C upgraded from version 0.01 to 0.02 + +That's a start. + +Once that's done, a more adventurous enhancement is to automate grabbing +the changelogs for dual lived modules. For each of them, grab the relevant +changes files from CPAN for the old and new versions, and if the old one is +a strict subset of the new one, splice the extra lines right into the output, +as a basis for summarising. + +(And if not, experiment with using F to get the relevant part of changelog +for the particular file in core) + +These could also be enhanced further by using a Pod parser module to produce +a parse tree of F, and splicing in the updates +correctly without throwing existing entries away. + +If you think that's nuts, take a look at what F already does to +splice into existing Makefiles on various platforms: + +http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498 + +Perl is this really powerful language for text manipulation. And fun to +play with. We need to get that message out. :-) + =item Utility Changes Changes to installed programs such as F and F go here. Most @@ -138,6 +175,61 @@ of these are built within the directories F and F. Changes which create B files in F go here. +B - this could be automated, at least as far as generating a first +draft. + +=over + +=item 1 + +Start with a clean exploded tarball of the previous release, and a clean +checkout of the branch in question + +=item 2 + +Take the F file of each + +=item 3 + +Search for lines matching C + +=item 4 + +Diff them + +=item 5 + +Explode if anyone deleted documentation. [No idea what the policy on that is +yet] + +=item 6 + +For each file only in the newer F + +=over + +=item 1 + +Use F to determine its Author + +=item 2 + +Open the pod file itself + +=item 3 + +Grab the description section + +=item 4 + +Write out a block of text starting roughly + + L, by A. U. Thor, provides @description + +=back + +=back + =item Changes to Existing Documentation Changes which significantly change existing files in F go here. @@ -174,6 +266,48 @@ Changes which create B files in F go here. Changes to existing files in F aren't worth summarising, although the bugs that they represent may be. +B - this could be automated, at least as far as generating a first +draft. + +=over + +=item 1 + +Start with a clean exploded tarball of the previous release, and a clean +checkout of the branch in question + +=item 2 + +Take the F file of each + +=item 3 + +Search for lines matching C (and I think also for new tests in +F) + +=item 4 + +Diff them + +=item 5 + +For each file only in the newer F + +=over + +=item 1 + +Grab the description line from F + +=item 2 + +Write out an =item section with the filename, and description, just like +L + +=back + +=back + =item Known Problems Descriptions of platform agnostic bugs we know we can't fix go here. Any diff --git a/pod/perltodo.pod b/pod/perltodo.pod index e94c749..d9f0aad 100644 --- a/pod/perltodo.pod +++ b/pod/perltodo.pod @@ -26,6 +26,24 @@ programming languages offer you 1 line of immortality? =head1 Tasks that only need Perl knowledge +=head2 Automate perldelta generation + +The perldelta file accompanying each release summaries the major changes. +It's mostly manually generated currently, but some of that could be +automated with a bit of perl, specifically the generation of + +=over + +=item Modules and Pragmata + +=item New Documentation + +=item New Tests + +=back + +See F for details. + =head2 Remove macperl references from tests MacPerl is gone. The tests don't need to be there.