This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
have corelist-perldelta.pl generate add'l sections
authorDavid Golden <dagolden@cpan.org>
Mon, 21 Dec 2009 05:06:11 +0000 (00:06 -0500)
committerDavid Golden <dagolden@cpan.org>
Mon, 21 Dec 2009 05:06:11 +0000 (00:06 -0500)
Porting/corelist-perldelta.pl
Porting/how_to_write_a_perldelta.pod
Porting/perldelta_template.pod

index b3aa772..c0aae08 100755 (executable)
@@ -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);
+
index 784d8e0..5a55095 100644 (file)
@@ -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
index 997c0eb..5161cea 100644 (file)
@@ -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