[tor-commits] [tor/master] Improve failure message from check-best-practices

[nickm at torproject.org]

commit e2512950b69d5f9f030673a15e8cf72b930538c7
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Mar 12 09:32:22 2019 -0400

    Improve failure message from check-best-practices
---
 doc/HACKING/HelpfulTools.md              | 15 +++++++++++++++
 scripts/maint/practracker/practracker.py |  9 ++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md
index d49923852..cba57e875 100644
--- a/doc/HACKING/HelpfulTools.md
+++ b/doc/HACKING/HelpfulTools.md
@@ -371,3 +371,18 @@ source code. Here's how to use it:
 
   6. See the Doxygen manual for more information; this summary just
      scratches the surface.
+
+Style and best-pratices checking
+--------------------------------
+
+We use scripts to check for various problems in the formatting and style
+of our source code.  The "check-spaces" test detects a bunch of violations
+of our coding style on the local level.  The "check-best-practices" test
+looks for violations of some of our complexity guidelines.
+
+You can tell the tool about exceptions to the complexity guidelines via its
+exceptions file (scripts/maint/practracker/exceptions.txt).  But before you
+do this, consider whether you shouldn't fix the underlying problem.  Maybe
+that file really _is_ too big.  Maybe that function really _is_ doing too
+much.  (On the other hand, for stable release series, it is sometimes better
+to leave things unrefactored.)
diff --git a/scripts/maint/practracker/practracker.py b/scripts/maint/practracker/practracker.py
index 541c5cbfb..08b74c264 100755
--- a/scripts/maint/practracker/practracker.py
+++ b/scripts/maint/practracker/practracker.py
@@ -133,7 +133,14 @@ def main():
 
     # If new issues were found, try to give out some advice to the developer on how to resolve it.
     if (found_new_issues):
-        new_issues_str = "practracker FAILED as indicated by the problem lines above. Please use the exceptions file ({}) to find any previous state of these problems. If you are unable to fix the underlying best-practices issue right now then you need to either update the relevant exception line or add a new one.".format(exceptions_file)
+        new_issues_str = """\
+FAILURE: practracker found new problems in the code: see warnings above.
+
+Please fix the problems if you can, and update the exceptions file
+({}) if you can't.
+
+See doc/HACKING/HelpfulTools.md for more information on using practracker.\
+""".format(exceptions_file)
         print(new_issues_str)
 
     sys.exit(found_new_issues)