CI: Support customizing CONTRIBUTORS in new contributor PRs (#2128)

When our source-maintenance.sh recognizes a magic phrase in a commit
message, it treats that commit as authoritative for CONTRIBUTORS file.
That feature allows us to customize CONTRIBUTORS by adding a magic
phrase to the commit message, preventing unwanted automated
collectAuthors() actions for earlier commits. Such commits work well
enough when CONTRIBUTORS is customized by an already known Squid
developer in a dedicated PR.

The same feature cannot work for PRs created by new developers because
when quick.yaml tests a PR, the first commit visible to collectAuthors()
is not a PR branch commit that the author could, with some considerable
trouble, customize, but a so called GitHub PR "merge commit" that GitHub
automatically creates with PR creator as the author. That merge commit
message does not contain PR description and never has our magic phrase.
That merge commit author details are wrong when PR creators want to use
information that differs from their public GitHub account info.

With this change, collectAuthors() consults PR description (when testing
PRs), allowing CONTRIBUTORS customization without any extra efforts:
Adding the magic phrase to PR description has to be done anyway.

diff --git a/.github/workflows/quick.yaml b/.github/workflows/quick.yaml
index bc2e3078e3e229c7376ddff76660831d31d9b05a..06bd1c076fa6abbb1dd24b84d98d9676c639ea1a 100644 (file)
--- a/.github/workflows/quick.yaml
+++ b/.github/workflows/quick.yaml
@@ -29,6 +29,9 @@ env:
   # empty except for pull_request events
   PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
 
+  # enables GitHub CLI (gh)
+  GH_TOKEN: ${{ github.token }}
+
   # Full clones of Squid repository branches (depth=19000+) waste resources,
   # while excessively shallow clones break tests that check for past commits
   # (e.g., to skip a particular test until a known bug is fixed) or generate

diff --git a/scripts/source-maintenance.sh b/scripts/source-maintenance.sh
index edaa782fd3bcbf368dfd76c84244992cf0c4e840..4ac7c02f7ff61140af4668ec5f392f9efbb0dfed 100755 (executable)
--- a/scripts/source-maintenance.sh
+++ b/scripts/source-maintenance.sh
@@ -707,11 +707,12 @@ run_ checkMakeNamedErrorDetails || exit 1
 # considered vetted:
 #
 # * authored (in "git log --author" sense) by squidadm,
-# * matching (in "git log --grep" sense) $vettedCommitPhraseRegex set below.
+# * matching (in "git log --grep" sense) $vettedPhraseRegex set below.
 #
 # A human authoring an official GitHub pull request containing a new
 # CONTRIBUTORS version (that they want to be used as a new vetting point)
-# should add a phrase matching $vettedCommitPhraseRegex to the PR description.
+# should add a phrase matching $vettedPhraseRegex to the PR description.
+# Doing so blocks this function from updating CONTRIBUTORS.
 #
 # [1] As defined by the --update-contributors-since script parameter.
 collectAuthors ()
@@ -721,13 +722,31 @@ collectAuthors ()
         return 0 # successfully did nothing, as requested
     fi
 
-    vettedCommitPhraseRegex='[Rr]eference point for automated CONTRIBUTORS updates'
+    vettedPhraseRegex='[Rr]eference point for automated CONTRIBUTORS updates'
+
+    vettedByPr=false
+    if test -n "${PULL_REQUEST_NUMBER}"
+    then
+        vettedByPr=`gh pr view $PULL_REQUEST_NUMBER --json body --jq ".body | test(\"${vettedPhraseRegex}\")"`
+        ghResult=$?
+        if test $ghResult -ne 0
+        then
+            echo "ERROR: Cannot determine whether the PR description contains the vetting phrase"
+            return $ghResult
+        fi
+    fi
+
+    if test "x$vettedByPr" = xtrue
+    then
+        echo 'successfully vetted by the PR description'
+        return 0
+    fi
 
     since="$UpdateContributorsSince"
     if test "x$UpdateContributorsSince" = xauto
     then
         # find the last CONTRIBUTORS commit vetted by a human
-        humanSha=`git log -n1 --format='%H' --grep="$vettedCommitPhraseRegex" CONTRIBUTORS`
+        humanSha=`git log -n1 --format='%H' --grep="$vettedPhraseRegex" CONTRIBUTORS`
         # find the last CONTRIBUTORS commit attributed to this script
         botSha=`git log -n1 --format='%H' --author=squidadm CONTRIBUTORS`
         if test "x$humanSha" = x && test "x$botSha" = x
@@ -765,7 +784,7 @@ collectAuthors ()
     # add collected new (co-)authors, if any, to CONTRIBUTORS
     ./scripts/update-contributors.pl --quiet < authors.tmp > CONTRIBUTORS.new || return
     updateIfChanged CONTRIBUTORS CONTRIBUTORS.new  \
-        "A human PR description should match: $vettedCommitPhraseRegex" || return
+        "A human PR description should match: $vettedPhraseRegex" || return
 
     rm -f authors.tmp
     return 0