Add directory-diff.pl script

MANIFEST

@@ -5912,6 +5912,7 @@ Porting/corelist.pl				Generates data for Module::CoreList
 Porting/corelist-diff				Tool to produce corelist diffs
 Porting/corelist-perldelta.pl			Generates data perldelta from Module::CoreList
 Porting/deparse-skips.txt			List of test files to ignore/skip for deparse tests.
+Porting/directory-diff.pl			Diff two directories
 Porting/docs-team-charter.pod			Perl Documentation Team charter
 Porting/epigraphs.pod				the release epigraphs used over the years
 Porting/exclude_contrib.txt			Data about contributors that do not want to be listed in AUTHORS

Porting/README.pod

@@ -132,6 +132,10 @@ produce election mailings, and all that sort of thing.
 
 List of test files to ignore/skip for deparse tests.
 
+=head2 F<directory-diff.pl>
+
+Compare two installation trees of perl.
+
 =head2 F<docs-team-charter.pod>
 
 The charter of the Perl Documentation Team

Porting/directory-diff.pl

@@ -0,0 +1,88 @@
+#!perl
+use 5.020;
+use feature 'signatures';
+no warnings 'experimental::signatures';
+
+use Getopt::Long;
+use Pod::Usage;
+use File::Find;
+use Algorithm::Diff 'diff';
+
+=head1 NAME
+
+directory-diff.pl - Output a diff between the filenames of two directories
+
+=head1 OPTIONS
+
+B<--expression>, B<-e> - apply the transformation to the filenames
+
+C<$_> will be set to the filename
+
+  -e 's/5\.10\.0/5.10.1/g'
+
+B<--expression-left>, B<-l> - apply the transformation to the filenames in the left directory
+
+B<--expression-right>, B<-r> - apply the transformation to the filenames in the right directory
+
+=cut
+
+GetOptions(
+    'expression|e=s' => \my $expr,
+    'left|l=s' => \my $left_expr,
+    'right|r=s' => \my $right_expr,
+);
+
+my $prev_release = ($] =~ s/(\d+)$/$1-1/re);
+$expr //= "s/$prev_release/$]/g";
+
+$left_expr //= $expr;
+$right_expr //= '';
+
+my $apply_expression_left = sub( $str ) {
+    $_ = $str;
+    eval $left_expr;
+    die $@ if $@;
+    return $_
+};
+
+my $apply_expression_right = sub( $str ) {
+    $_ = $str;
+    eval $left_expr;
+    die $@ if $@;
+    return $_
+};
+
+sub read_tree( $dir ) {
+    my @files;
+    File::Find::find( { wanted => sub {
+        push @files, $File::Find::name
+            if -f $File::Find::name
+    }}, $dir);
+    return sort @files
+}
+
+my ($dir_left, $dir_right) = @ARGV;
+
+my @left  = map { s/^\Q$dir_left//;  $apply_expression_left->( $_ )  } read_tree( $dir_left );
+my @right = map { s/^\Q$dir_right//; $apply_expression_right->( $_ ) } read_tree( $dir_right );
+
+my $diff = Algorithm::Diff->new( \@left, \@right );
+$diff->Base( 1 );   # Return line numbers, not indices
+while(  $diff->Next()  ) {
+    next   if  $diff->Same();
+    my $sep = '';
+    if(  ! $diff->Items(2)  ) {
+        printf "%d,%dd%d\n",
+            $diff->Get(qw( Min1 Max1 Max2 ));
+    } elsif(  ! $diff->Items(1)  ) {
+        printf "%da%d,%d\n",
+            $diff->Get(qw( Max1 Min2 Max2 ));
+    } else {
+        $sep = "---\n";
+        printf "%d,%dc%d,%d\n",
+            $diff->Get(qw( Min1 Max1 Min2 Max2 ));
+    }
+    say "< $dir_left$_"   for  $diff->Items(1);
+    print $sep;
+    say "> $dir_right$_"   for  $diff->Items(2);
+}

Porting/release_managers_guide.pod

@@ -213,6 +213,13 @@ asked to compare the installed files with a previous install. Save yourself
 some time on release day, and have a (clean) install of the previous
 version ready.
 
+=head3 Install convenience modules in your main Perl
+
+Some of the tools in C<Porting/> require modules from CPAN. You can install
+these to your main Perl through the package manager of your choice:
+
+  cpan Algorithm::Diff
+
 =head3 Email account subscribed to perl5-porters
 
 In order for your release announcement email to be delivered to the
@@ -1145,12 +1152,17 @@ Compare the pathnames of all installed files with those of the previous
 release (i.e. against the last installed tarball on this branch which you
 have previously verified using this same procedure). In particular, look
 for files in the wrong place, or files no longer included which should be.
-For example, suppose the about-to-be-released version is 5.10.1 and the
-previous is 5.10.0:
+For example, suppose the about-to-be-released version is 5.43.6 and the
+previous is 5.43.7:
+
+ perl Porting/directory-diff.pl -l 's/5.43.6/5.43.7/g' /tmp/perl-5.43.6 /tmp/perl-5.43.7
+
+Alternatively, if you didn't install C<Algorithm::Diff> into your main Perl,
+you can do the manual steps in the shell:
 
- $ cd installdir-5.10.0/
- $ find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
- $ cd installdir-5.10.1/
+ $ cd installdir-5.43.6/
+ $ find . -type f | perl -pe's/5\.43\.6/5.43.7/g' | sort > /tmp/f1
+ $ cd installdir-5.43.7/
  $ find . -type f | sort > /tmp/f2
  $ diff -u /tmp/f[12]
 

t/porting/known_pod_issues.dat

@@ -436,6 +436,6 @@ pod/perltie.pod	Verbatim line length including indents exceeds 78 by	3
 pod/perltru64.pod	Verbatim line length including indents exceeds 78 by	1
 porting/bisect-runner.pl	Verbatim line length including indents exceeds 78 by	2
 porting/epigraphs.pod	Verbatim line length including indents exceeds 78 by	-1
-porting/release_managers_guide.pod	Verbatim line length including indents exceeds 78 by	8
+porting/release_managers_guide.pod	Verbatim line length including indents exceeds 78 by	9
 lib/benchmark.pm	Verbatim line length including indents exceeds 78 by	2
 lib/config.pod	? Should you be using L<...> instead of	-1

t/porting/utils.t

@@ -49,6 +49,7 @@ close $fh or die $!;
 
 my @victims = (qw(installman installperl regen_perly.pl));
 my %excuses = (
+               'Porting/directory-diff.pl' => 'Algorithm::Diff',
                'Porting/git-deltatool' => 'Git::Wrapper',
                'Porting/podtidy' => 'Pod::Tidy',
                'Porting/leakfinder.pl' => 'XS::APItest',