diff options
author | Nicholas Clark <nick@ccl4.org> | 2009-09-14 16:51:09 +0100 |
---|---|---|
committer | Nicholas Clark <nick@ccl4.org> | 2009-09-14 16:55:33 +0100 |
commit | 0be987a291dca2e27ebe17569a5442b14fcaa944 (patch) | |
tree | 6f6dce91c3c8dd54c0a484bb43f3665df75a51b0 /Porting/how_to_write_a_perldelta.pod | |
parent | eeab323ffcafa032cc1de5436f6cd56bea0372ea (diff) | |
download | perl-0be987a291dca2e27ebe17569a5442b14fcaa944.tar.gz |
Note how various parts of perldelta writing could be automated.
Diffstat (limited to 'Porting/how_to_write_a_perldelta.pod')
-rw-r--r-- | Porting/how_to_write_a_perldelta.pod | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod index 53265bd75c..66f7adcb20 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<ext/> and F<lib/> by module, and then summarise all changes to a module as a group. This can be done by partitioning directories within F<ext/> and F<lib/> to a number of people. +B<FIXME> - this could be automated, although the two below would be easier +to start with. + +Start with F<Porting/cmpVERSION.pl> + +Augment it with a flag, so that instead of reporting which modules are +different but have the same version, report on modules which I<are> different. +Grab the old version from the exploded tarball, and the new version from +the git checkout, and output the line + + =item * + + C<less> 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<git> 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<perl${whatever}delta.pod>, and splicing in the updates +correctly without throwing existing entries away. + +If you think that's nuts, take a look at what F<pod/buildtoc> 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<perlbug> and F<xsubpp> go here. Most @@ -138,6 +175,61 @@ of these are built within the directories F<utils> and F<x2p>. Changes which create B<new> files in F<pod/> go here. +B<FIXME> - 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<MANIFEST> file of each + +=item 3 + +Search for lines matching C<m!^pod/.*\.pod!> + +=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<MANIFEST> + +=over + +=item 1 + +Use F<git> 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<perlfoo>, by A. U. Thor, provides @description + +=back + +=back + =item Changes to Existing Documentation Changes which significantly change existing files in F<pod/> go here. @@ -174,6 +266,48 @@ Changes which create B<new> files in F<t/> go here. Changes to existing files in F<t/> aren't worth summarising, although the bugs that they represent may be. +B<FIXME> - 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<MANIFEST> file of each + +=item 3 + +Search for lines matching C<m!t/.*\.t!> (and I think also for new tests in +F<ext/DynaLoader>) + +=item 4 + +Diff them + +=item 5 + +For each file only in the newer F<MANIFEST> + +=over + +=item 1 + +Grab the description line from F<MANIFEST> + +=item 2 + +Write out an =item section with the filename, and description, just like +L<http://perl5.git.perl.org/perl.git/blob/maint-5.10:/pod/perl5101delta.pod> + +=back + +=back + =item Known Problems Descriptions of platform agnostic bugs we know we can't fix go here. Any |