Add a way to rename authors properly

With the removal of the redundant data from .mailmap
we lacked a way to rename an author properly. Previously
someone could manually update a name or email in AUTHORS
files and things would "just work" as the .mailmap file would
tell us the old mapping. Now we have removed those mappings
we need a way to easily rename someones canonical data.
This also means manually changing the AUTHORS file is now a
problem.

AUTHORS

@@ -12,41 +12,9 @@
 # is strictly forbidden.  (Passive distribution with the Perl source
 # code kit is, of course, allowed.)
 #
-# This file is one of three files that we use to keep track of our
-# contributors, and is coupled with C<.mailmap> and
-# C<Porting/exclude_contrib.txt> in being used to manage our contributor
-# data. F<AUTHORS> serves the role of designating the "canonical name"
-# and "canonical email" for our contributors. It will be updated
-# automatically from commit data when new contributors have code that is
-# merged. It also may be manually edited in some cases, such as adding a
-# contributor with no commits, or modifying the canonical details of a
-# contributor.
-#
-# Any person listed here will have .mailmap entries created so that
-# their visible presence on GitHub and casual git operations shows as
-# indicated in this file. If the person is listed WITHOUT an email
-# address then the email in git tool will be shown as unknown. This may
-# be used because contributors choose to withdraw from the project and
-# are unreachable but still deserve recognition, or even possibly
-# because they are deceased.
-#
-# Every entry in this file should also appear on the left hand side of
-# at least one entry in F<.mailmap> (this may change), and if you
-# modify a persons name or email (but not both together)then
-# F<Porting/updateAUTHORS.pl> will update F<.mailmap> as appropriate
-# based on the changes. If you want to update both at the same time
-# then do it in two steps, running F<Porting/updateAUTHORS.pl> after
-# each change.
-#
-# Lastly some users have contributed to the project but choose not to be
-# listed here. We respect these requests, and support them. Simply
-# delete the entries from this file and .mailmap and then run
-#
-#   Porting/updateAUTHORS.pl --exclude
-#
-# and new exclude records will be added to F<Porting/exclude_contrib.txt>
-# to prevent the author from being readded by F<Porting/updateAUTHORS.pl>
-# in the future.
+# This file is managed by the Porting/updateAUTHORS.pl script along
+# with several other files, F<.mailmap> and F<Porting/exclude_contrib.txt>
+# generally you should use Porting/updateAUTHORS.pl to make any changes.
 #
 -- 
 A. C. Yardley                  <yardley@tanet.net>

Porting/updateAUTHORS.pl

@@ -72,8 +72,17 @@ sub main {
             # support hyphens as well as underbars,
             # underbars must be first. Only handles two
             # part words right now.
-            s/\b([a-z]+)_([a-z]+)\b/${1}_${2}|${1}-${2}/gr
-        } @OPTSPEC
+            ref $_ ? $_ : s/\b([a-z]+)_([a-z]+)\b/${1}_${2}|${1}-${2}/gr
+        }
+        @OPTSPEC,
+        (map { $opts{$_}= {};
+               ("$_=s%" => $opts{$_})
+           } qw(
+            change_name_for_name|change_name
+            change_name_for_email
+            change_email_for_name
+            change_email_for_email|change_email
+        )),
     ) or pod2usage(2);
     $opts{commit_range}= join " ", @ARGV;
     if (!$opts{commit_range}) {
@@ -303,6 +312,13 @@ =head1 SYNOPSIS
    --exclude            Add new names to the exclude file so they never
                         appear in AUTHORS or .mailmap.
 
+ Details Changes
+    Update canonical name or email in AUTHORS and .mailmap properly.
+    --change-name           OLD_NAME=NEW_NAME
+    --change_name_for_email OLD_ADDR=NEW_NAME
+    --change_email_for_name OLD_NAME=NEW_ADDR
+    --change_email          OLD_ADDR=NEW_EMAIL
+
  Reports About People
     --stats             detailed report of authors and what they did
     --who               Sorted, wrapped list of who did what
@@ -459,6 +475,26 @@ =head1 OPTIONS
 Show an additional column with the rank number of a row in the report in
 reports that do not normally show the rank number.
 
+=item C<--change-name OLD_NAME=NEW_NAME>
+
+=item C<--change-name-for-email OLD_EMAIL=NEW_NAME>
+
+=item C<--change-email OLD_EMAIL=NEW_EMAIL>
+
+=item C<--change-email-for-name OLD_NAME=NEW_EMAIL>
+
+Change email or name based on OLD_NAME or OLD_EMAIL.
+
+Eg,
+
+    --change-name-for-email somebody@gmail.com="Bob Rob"
+
+would cause the preferred name for the person with the preferred email
+C<somebody@gmail.com> to change to "Bob Rob" in our records. If that
+persons name was "Daniel Dude" then we might have done this as well:
+
+    --change-name "Bob Rob"="Daniel Dude"
+
 =back
 
 =head1 DESCRIPTION
@@ -485,16 +521,13 @@ =head1 DESCRIPTION
 
 =head2 ADDING A NEW CONTRIBUTOR
 
-Run the tool with no arguments. It will add anything that is missing.
-Check the changes and then commit them.
+Commit your changes. Run the tool with no arguments. It will add
+anything that is missing. Check the changes and then commit them.
 
 =head2 CHANGING A CONTRIBUTORS CANONICAL NAME OR EMAIL
 
-Manually modify F<AUTHORS> so that the name or email is correct. Run the
-tool with no arguments, it should update C<.mailmap> appropriately.
-Check the changes before you commit them. If you wish to change BOTH
-files at the same time you should do it in two steps, running the tool
-in between each step. Check the changes and then commit them.
+Use the C<--change-name-for-name> and related options. This will do
+things "properly" and update all the files.
 
 =head2 A CONTRIBUTOR WANTS TO BE FORGOTTEN
 

Porting/updateAUTHORS.pm

@@ -321,8 +321,25 @@ sub read_authors {
         $copy =~ s/\s+\z//;
         $name= $copy;
         $email //= "unknown";
+        my $orig_name= $name;
+        my $orig_email= $email;
+        if (my $new_name= $self->{change_name_for_name}{$orig_name}) {
+            $name= $new_name;
+        }
+        if (my $new_name= $self->{change_name_for_email}{$orig_email}) {
+            $name= $new_name;
+        }
+        if (my $new_email= $self->{change_email_for_name}{$orig_name}) {
+            $email= $new_email;
+        }
+        if (my $new_email= $self->{change_email_for_email}{$orig_email}) {
+            $email= $new_email;
+        }
+        $line= sprintf "%-31s%s", $name, $email=~/^\@/ ? $email : "<$email>";
+        $line=~s/\s+<unknown>\z//;
         $email= lc($email);
 
+        $line=~s/\s+\z//;
         $author_info{"lines"}{$line}++;
         $author_info{"email2line"}{$email}= $line
             if $email and $email ne "unknown";
@@ -498,9 +515,22 @@ sub parse_orig_mailmap_hash {
             die encode_utf8 "Both preferred name and email are mandatory ",
                 "in line num $line_num: '$line'";
         }
+        my ($name, $email, $other_name, $other_email)= ($1,$2,$3,$4);
+        my ($orig_name, $orig_email)= ($1,$2);
+        if (my $new_name= $self->{change_name_for_name}{$orig_name}) {
+            $name= $new_name;
+        }
+        if (my $new_name= $self->{change_name_for_email}{$orig_email}) {
+            $name= $new_name;
+        }
+        if (my $new_email= $self->{change_email_for_name}{$orig_name}) {
+            $email= $new_email;
+        }
+        if (my $new_email= $self->{change_email_for_email}{$orig_email}) {
+            $email= $new_email;
+        }
 
-        # [ preferred_name, preferred_email, other_name, other_email ]
-        push @recs, [ $1, $2, $3, $4, $line_num ];
+        push @recs, [ $name, $email, $other_name, $other_email, $line_num ];
     }
     return \@recs;
 }