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

@@ -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):