diff options
| -rwxr-xr-x | Porting/corelist-perldelta.pl | 93 | ||||
| -rw-r--r-- | Porting/how_to_write_a_perldelta.pod | 14 | ||||
| -rw-r--r-- | Porting/perldelta_template.pod | 37 |
3 files changed, 103 insertions, 41 deletions
diff --git a/Porting/corelist-perldelta.pl b/Porting/corelist-perldelta.pl index b3aa772756..c0aae08bc4 100755 --- a/Porting/corelist-perldelta.pl +++ b/Porting/corelist-perldelta.pl @@ -6,6 +6,50 @@ use lib 'Porting'; use Maintainers qw/%Modules/; use Module::CoreList; +my $deprecated; + +#--------------------------------------------------------------------------# + +sub added { + my ($mod, $old_v, $new_v) = @_; + say "=item C<$mod>\n"; + say "Version $new_v has been added to the Perl core.\n"; +} + +sub updated { + my ($mod, $old_v, $new_v) = @_; + say "=item C<$mod>\n"; + say "Upgraded from version $old_v to $new_v.\n"; + if ( $deprecated->{$mod} ) { + say "NOTE: C<$mod> is deprecated and may be removed from a future version of Perl.\n"; + } +} + +sub removed { + my ($mod, $old_v, $new_v) = @_; + say "=item C<$mod>\n"; + say "Removed from the Perl core. Prior version was $old_v.\n"; +} + +sub generate_section { + my ($title, $item_sub, @mods ) = @_; + return unless @mods; + + say "=head2 $title\n"; + say "=over 4\n"; + + for my $tuple ( sort { lc($a->[0]) cmp lc($b->[0]) } @mods ) { + my ($mod,$old_v,$new_v) = @$tuple; + $old_v //= q('undef'); + $new_v //= q('undef'); + $item_sub->($mod, $old_v, $new_v); + } + + say "=back\n"; +} + +#--------------------------------------------------------------------------# + my $corelist = \%Module::CoreList::version; my @versions = sort keys %$corelist; @@ -14,15 +58,46 @@ my ($old, $new) = @ARGV; $old ||= $versions[-2]; $new ||= $versions[-1]; -say "=head2 Updated Modules\n"; -say "=over 4\n"; +$deprecated = $Module::CoreList::deprecated{$new}; -for my $mod ( sort { lc $a cmp lc $b } keys %Modules ) { - my $old_ver = $corelist->{$old}{$mod}; - my $new_ver = $corelist->{$new}{$mod}; - next unless defined $old_ver && defined $new_ver && $old_ver ne $new_ver; - say "=item C<$mod>\n"; - say "Upgraded from version $old_ver to $new_ver.\n"; +my (@new,@deprecated,@removed,@pragmas,@modules); + +# %Modules defines what is currently in core +for my $k ( keys %Modules ) { + next unless exists $corelist->{$new}{$k}; + my $old_ver = $corelist->{$old}{$k}; + my $new_ver = $corelist->{$new}{$k}; + # in core but not in last corelist + if ( ! exists $corelist->{$old}{$k} ) { + push @new, [$k, undef, $new_ver]; + } + # otherwise just pragmas or modules + else { + my $old_ver = $corelist->{$old}{$k}; + my $new_ver = $corelist->{$new}{$k}; + next unless defined $old_ver && defined $new_ver && $old_ver ne $new_ver; + my $tuple = [ $k, $old_ver, $new_ver ]; + if ( $k eq lc $k ) { + push @pragmas, $tuple; + } + else { + push @modules, $tuple; + } + } } -say "=back\n"; +# in old corelist, but not this one => removed +# N.B. This is exhaustive -- not just what's in %Modules, so modules removed from +# distributions will show up here, too. Some person will have to review to see what's +# important. That's the best we can do without a historical Maintainers.pl +for my $k ( keys %{ $corelist->{$old} } ) { + if ( ! exists $corelist->{$new}{$k} ) { + push @removed, [$k, $corelist->{$old}{$k}, undef]; + } +} + +generate_section("New Modules and Pragmata", \&added, @new); +generate_section("Pragmata Changes", \&updated, @pragmas); +generate_section("Updated Modules", \&updated, @modules); +generate_section("Removed Modules and Pragmata", \&removed, @removed); + diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod index 784d8e0af2..5a55095f7d 100644 --- a/Porting/how_to_write_a_perldelta.pod +++ b/Porting/how_to_write_a_perldelta.pod @@ -132,13 +132,23 @@ within F<ext/> and F<lib/> to a number of people. B<FIXME> - this could be automated better If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl> -will automatically print out this section following a template like this: +will automatically print out several sections if relevent that can be +pasted into F<perldelta>: + + * New Modules and Pragmata + * Pragmata Changes + * Updated Modules + * Removed Modules and Pragmata + +Each section will have stub entries following a template like this: =item C<less> Upgraded from version 0.01 to 0.02 -That's a start and the output can be copied/inserted into the perldelta. +It does not include modules listed in F<Porting/Maintainers.pl> under +C<_PERLLIB>, but it's a start. Where relevent, a summary of changes can be +added by hand. A more adventurous enhancement would be to automate grabbing the changelogs for dual lived modules. For each of them, grab the relevant diff --git a/Porting/perldelta_template.pod b/Porting/perldelta_template.pod index 997c0eb203..5161ceacaa 100644 --- a/Porting/perldelta_template.pod +++ b/Porting/perldelta_template.pod @@ -42,43 +42,20 @@ source tree. =head1 Modules and Pragmata XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/> -go here, in a list ordered by distribution name. Minimally it should be the -module version, but it's more useful to the end user to give a paragraph's -summary of the module's changes. In an ideal world, dual-life modules would -have a F<Changes> file that could be cribbed. +go here. If Module::CoreList is updated, generate an initial draft of the +following sections using F<Porting/corelist-perldelta.pl>, which prints stub +entries to STDOUT. Results can be pasted in place of the '=head2' entries +below. A paragraph summary for important changes should then be added by hand. +In an ideal world, dual-life modules would have a F<Changes> file that could be +cribbed. =head2 New Modules and Pragmata -=over 4 - -=item C<XXX> - -XXX - -=back - =head2 Pragmata Changes -=over 4 - -=item C<XXX> - -XXX - -=back - =head2 Updated Modules -XXX If Module::CoreList is updated, generate this section using -F<Porting/corelist-perldelta.pl> - -=over 4 - -=item C<XXX> - -XXX - -=back +=head2 Removed Modules and Pragmata =head1 Utility Changes |