From b8982ec5f90a5aa9d802e9d54912dc4e7ba0916a Mon Sep 17 00:00:00 2001
From: Jim Mussared <jim.mussared@gmail.com>
Date: Fri, 5 Aug 2022 13:55:56 +1000
Subject: [PATCH] tools/verifygitlog.py: Add additional help for subject line
 issues.

This check used to just show the regular expression that failed to match,
but the rules are pretty subtle and hard to interpret from the regular
expression alone.

Add some basic checks for the main things that go wrong:
 - Missing capitalisation.
 - Missing full-stop.
 - Missing path.
 - Single-word subject.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
---
 tools/verifygitlog.py | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/tools/verifygitlog.py b/tools/verifygitlog.py
index 5d45e4a4c..c237cb46b 100755
--- a/tools/verifygitlog.py
+++ b/tools/verifygitlog.py
@@ -46,6 +46,23 @@ def git_log(pretty_format, *args):
         yield line.decode().rstrip("\r\n")
 
 
+def diagnose_subject_line(subject_line, subject_line_format, err):
+    err.error("Subject line: " + subject_line)
+    if not subject_line.endswith("."):
+        err.error('* should end with "."')
+    if not re.match(r"^[^!]+: ", subject_line):
+        err.error('* should start with "path: "')
+    if re.match(r"^[^!]+: *$", subject_line):
+        err.error("* should contain a subject after the path.")
+    m = re.match(r"^[^!]+: ([a-z][^ ]*)", subject_line)
+    if m:
+        err.error('* first word of subject ("{}") should be capitalised.'.format(m.group(1)))
+    if re.match(r"^[^!]+: [^ ]+$", subject_line):
+        err.error("* subject should contain more than one word.")
+    err.error("* should match: " + repr(subject_line_format))
+    err.error('* Example: "py/runtime: Add support for foo to bar."')
+
+
 def verify(sha, err):
     verbose("verify", sha)
     err.prefix = "commit " + sha + ": "
@@ -75,9 +92,9 @@ def verify_message_body(raw_body, err):
     very_verbose("subject_line", subject_line)
     subject_line_format = r"^[^!]+: [A-Z]+.+ .+\.$"
     if not re.match(subject_line_format, subject_line):
-        err.error("Subject line should match " + repr(subject_line_format) + ": " + subject_line)
+        diagnose_subject_line(subject_line, subject_line_format, err)
     if len(subject_line) >= 73:
-        err.error("Subject line should be 72 or less characters: " + subject_line)
+        err.error("Subject line should be 72 or fewer characters: " + subject_line)
 
     # Second one divides subject and body.
     if len(raw_body) > 1 and raw_body[1]:
@@ -90,7 +107,7 @@ def verify_message_body(raw_body, err):
             err.error("Message lines should be 75 or less characters: " + line)
 
     if not raw_body[-1].startswith("Signed-off-by: ") or "@" not in raw_body[-1]:
-        err.warning("Message should be signed-off")
+        err.warning('Message should be signed-off. Use "git commit -s".')
 
 
 def run(args):