updateAUTHORS.p[lm] - add exclusion support

This add a new file Porting/exclude_contrib.txt to hold a list
of base64 SHA-256 digests of the user name and email who should be
excluded.

This adds the options

    --exclude-me
    --exclude-contrib=NAME_AND_EMAIL
    --exclude-missing

to add exclusions in different ways. --exclude-me uses the git
credentials for the current user, --exclude-contrib expects a name
and email, and --exclude-missing excludes someone who is missing from
the change log.

When excluding someone their name will be removed from AUTHORS if it is
already listed, and the relevant entries to .mailmap will be removed,
and if necessary additional exclusion entries will be added for any of
their old identities which were mentioned in .mailmap.

This feature will be used in a later patch to resolve GH issue Perl#20010.

Author: demerphq

.mailmap

@@ -6,10 +6,6 @@
 # Each line specifies the canonical name and email for a developer
 # and mapping data from other names and email addresses.
 #
-# Every developer who has worked on the project should have at least
-# one entry in this file, and should have one entry per every distinct
-# name/email combination they have used while working on the project.
-#
 # The mapping works from *right* to *left*, that is the definition
 # on the left specifies the "preferred email", the definition on the
 # right specifies the "other email". The "preferred email" is what
@@ -53,8 +49,7 @@
 # Please do NOT add comments after the header block.
 #
 # See also: https://git-scm.com/docs/gitmailmap
-# However be aware, we do not support all the forms that git does. We
-# want to have one entry per actually use author/commit data.
+# However be aware, we do not support all the forms that git does.
 #
 ########################################################################
 A. C. Yardley <[email protected]> A. C. Yardley <[email protected]>

MANIFEST

@@ -5412,6 +5412,7 @@ 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/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/exec-bit.txt		List of files that get +x in release tarball
 Porting/exercise_makedef.pl	Brute force testing for makedef.pl
 Porting/expand-macro.pl		A tool to expand C macro definitions in the Perl source

Porting/README.pod

@@ -146,6 +146,11 @@ The charter of the Perl Documentation Team
 
 List of Perl release epigraphs.
 
+=head2 F<exclude_contrib.txt>
+
+List of base 64 encoded SHA256 digests of C<< "name <email>" >> data
+which should be ignored by F<updateAUTHORS.pl>.
+
 =head2 F<exec-bit.txt>
 
 This file contains a list of files that F<makerel> will ensure get an
@@ -403,4 +408,3 @@ leaks.
 Guide for Vote Administrators for running Steering Council elections.
 
 =cut
-

Porting/exclude_contrib.txt

@@ -0,0 +1,21 @@
+##########################################################################
+# This file is managed by `Porting/updateAUTHORS.pl`
+#
+# It contains the base 64 SHA-256 of the name and email details of the
+# contributors who have requested that their gracious contributions go
+# unnoted in our AUTHORS file, and who choose not to be listed in our
+# .mailmap files either.
+#
+# For example the user details
+#
+#     Joe <[email protected]>
+#
+# would be excluded via entry
+#
+#     UkM6tKuf79Ra0HH7wQj6YUXumpjWy6Qd3aB5+HoNoGM
+#
+# To update this file you should use one of the --exclude options to
+# `Porting/updateAUTHORS.pl`, but if you *must* manually edit it then make
+# sure you run the tool afterwards to ensure it is correctly formatted and
+# sorted.
+##########################################################################

Porting/updateAUTHORS.pl

@@ -22,6 +22,9 @@ package App::Porting::updateAUTHORS;
     mailmap_file=s
 
     verbose+
+    exclude_missing|exclude
+    exclude_contrib=s@
+    exclude_me
 
     from_commit|from=s
     to_commit|to=s
@@ -32,8 +35,10 @@ sub main {
     my %opts= (
         authors_file => "AUTHORS",
         mailmap_file => ".mailmap",
+        exclude_file => "Porting/exclude_contrib.txt",
         from         => "",
         to           => "",
+        exclude_contrib => [],
     );
 
     ## Parse options and print usage if there is a syntax error,
@@ -58,6 +63,17 @@ sub main {
     pod2usage(1)             if $opts{help};
     pod2usage(-verbose => 2) if $opts{man};
 
+    if (delete $opts{exclude_me}) {
+        my ($author_full)= Porting::updateAUTHORS->current_author_name_email("full");
+        my ($committer_full)= Porting::updateAUTHORS->current_committer_name_email("full");
+
+        push @{$opts{exclude_contrib}}, $author_full
+            if $author_full;
+        push @{$opts{exclude_contrib}}, $committer_full
+            if $committer_full and (!$author_full or
+               $committer_full ne $author_full);
+    }
+
     my $self= Porting::updateAUTHORS->new(%opts);
 
     my $changed= $self->read_and_update();
@@ -73,7 +89,7 @@ sub main {
 =head1 NAME
 
 F<Porting/updateAUTHORS.pl> - Automatically update F<AUTHORS> and F<.mailmap>
-based on commit data.
+and F<Porting/exclude_contrib.txt> based on commit data.
 
 =head1 SYNOPSIS
 
@@ -96,6 +112,15 @@ =head1 SYNOPSIS
    --authors-file=FILE  override default of 'AUTHORS'
    --mailmap-file=FILE  override default of '.mailmap'
 
+ Action Modifiers
+   --exclude-missing    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.
+    --exclude-contrib       NAME_AND_EMAIL
+    --exclude-me
+
 =head1 OPTIONS
 
 =over 4
@@ -126,6 +151,60 @@ =head1 OPTIONS
 Override the default location of the mailmap file, which is by default
 the F<.mailmap> file in the current directory.
 
+=item C<--exclude-file=FILE>
+
+=item C<--exclude_file=FILE>
+
+Override the default location of the exclude file, which is by default
+the F<Porting/exclude_contrib.txt> file reachable from the current
+directory.
+
+=item C<--exclude-contrib=NAME_AND_EMAIL>
+
+=item C<--exclude_contrib=NAME_AND_EMAIL>
+
+Exclude a specific name/email combination from our contributor datasets.
+Can be repeated multiple times on the command line to remove multiple
+items at once. If the contributor details correspond to a canonical
+identity of a contributor (one that is in the AUTHORS file or on the
+left in the .mailmap file) then ALL records, including those linked to
+that identity in .mailmap will be marked for exclusion. This is similar
+to C<--exclude-missing> but it only affects the specifically named
+users. Note that the format for NAME_AND_EMAIL is similar to that of the
+.mailmap file, email addresses and C< @github > style identifiers should
+be wrapped in angle brackets like this: C<< <@github> >>, users with no
+email in the AUTHORS file should use C<< <unknown> >>.
+
+For example:
+
+  Porting/updateAUTHORS.pl --exclude-contrib="Joe B <[email protected]>"
+
+Would remove all references to "Joe B" from F<AUTHORS> and F<.mailmap>
+and add the required entires to F<Porting/exclude_contrib.txt> such that
+the contributor would never be automatically added back, and would be
+automatically removed should someone read them manually.
+
+=item C<--exclude-missing>
+
+=item C<--exclude_missing>
+
+=item C<--exclude>
+
+Normally when the tool is run it *adds* missing data only. If this
+option is set then the reverse will happen, any author data missing will
+be marked as intentionally missing in such a way that future "normal"
+runs of the script ignore the author(s) that were excluded.
+
+The exclude data is stored in F<Porting/exclude_contrib.txt> as a SHA256
+digest (in base 64) of the user name and email being excluded so that
+the list itself doesnt contain the contributor details in plain text.
+
+The general idea is that if you want to remove someone from F<AUTHORS>
+and F<.mailmap> you delete their details manually, and then run this
+tool with the C<--exclude> option. It is probably a good idea to run it
+first without any arguments to make sure you dont exclude something or
+someone you did not intend to.
+
 =back
 
 =head1 DESCRIPTION