doc: hall of fame: support correcting names that are wrong

We identified somebody whose name was malformed in git history such that
they were credited wrong in the hall of fame, so add some code to handle
names that manage to be committed with incorrect formatting.

Signed-off-by: Peter Marheine <pmarheine@chromium.org>
Change-Id: I33b04932403b2d69da4648a3a7016aee57741d0d
Reviewed-on: https://review.coreboot.org/c/flashrom/+/88477
Reviewed-by: Anastasia Klimchuk <aklm@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

doc/_ext/flashrom_authors.py

@@ -1,3 +1,4 @@
+import collections
 from docutils import nodes
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -13,17 +14,14 @@ class FlashromAuthorsDirective(SphinxDirective):
     required_arguments = 1
     has_content = True
 
-    def make_table(self, list_file: Path):
+    def make_table(self, name_counts):
         body = nodes.tbody()
-        with list_file.open("r") as f:
+        for name, count in name_counts:
-            for line in f:
+            body += nodes.row(
-                count, _, name = line.strip().partition("\t")
+                "",
-
+                nodes.entry("", nodes.paragraph(text=name)),
-                body += nodes.row(
+                nodes.entry("", nodes.paragraph(text=str(count))),
-                    "",
+            )
-                    nodes.entry("", nodes.paragraph(text=name)),
-                    nodes.entry("", nodes.paragraph(text=count)),
-                )
 
         return nodes.table(
             "",
@@ -68,7 +66,40 @@ class FlashromAuthorsDirective(SphinxDirective):
             self.state.nested_parse(self.content, 0, container)
             return [self.make_placeholder(container.children)]
         else:
-            return [self.make_table(Path(list_file))]
+            authors = self.count_authors_from_file(Path(list_file))
+            return [self.make_table(authors.most_common())]
+
+    @classmethod
+    def count_authors_from_file(cls, list_file: Path) -> collections.Counter:
+        # Correcting names may influence the count, so although git shortlog
+        # provides us a count there may be multiple entries in the file that
+        # must be combined into a single row.
+        counter = collections.Counter()
+
+        with list_file.open("r") as f:
+            for line in f:
+                count, _, name = line.strip().partition("\t")
+                fixed_name = cls._correct_known_bad_name(name)
+                if fixed_name is not None:
+                  counter[fixed_name] += int(count)
+
+        return counter
+
+    _INCORRECT_NAMES = {
+        # Commit 9ff3d4cf759161edf6c163f454f11bc9f5328ce3 is missing a '>' in a
+        # Co-Authored-By trailer, but this person is already credited as author
+        # of that commit so should not be double-counted.
+        "persmule <persmule@hardenedlinux.org": None,
+    }
+
+    @classmethod
+    def _correct_known_bad_name(cls, name: str):
+        """
+        Return a corrected form of the provided name if it's known to be
+        incorrect and should be modified, or None if the name should be
+        ignored.  Otherwise, return the provided name.
+        """
+        return cls._INCORRECT_NAMES.get(name, name)
 
 
 def setup(app: Sphinx) -> 'ExtensionMetadata':