commit 5b3741e05ac82cbe99942cffdc5662bd53c783dc Author: Nick Mathewson nickm@torproject.org Date: Wed Aug 21 10:00:05 2019 -0400
Document new practracker violation types, and add a practracker readme
Closes ticket 31476. --- Makefile.am | 1 + scripts/maint/practracker/README | 21 +++++++++++++++++++++ scripts/maint/practracker/practracker.py | 11 ++++++++--- 3 files changed, 30 insertions(+), 3 deletions(-)
diff --git a/Makefile.am b/Makefile.am index d3cce3934..0800497dc 100644 --- a/Makefile.am +++ b/Makefile.am @@ -168,6 +168,7 @@ EXTRA_DIST+= \ ReleaseNotes \ scripts/maint/checkIncludes.py \ scripts/maint/checkSpace.pl \ + scripts/maint/practracker/README \ scripts/maint/practracker/exceptions.txt \ scripts/maint/practracker/includes.py \ scripts/maint/practracker/metrics.py \ diff --git a/scripts/maint/practracker/README b/scripts/maint/practracker/README new file mode 100644 index 000000000..d2ad8220c --- /dev/null +++ b/scripts/maint/practracker/README @@ -0,0 +1,21 @@ +Practracker is a simple python tool that keeps track of places where +our code is ugly, and tries to warn us about new ones or ones that +get worse. + +Right now, practracker looks for the following kinds of +best-practices violations: + + C files greater than 3000 lines long + H files greater than 500 lines long + C files with more than 50 includes + H files with more than 15 includes + + All files that include a local header not listed in a .may_include + file in the same directory, when that .may_include file has an + "!advisory" marker. + +The list of current violations is tracked in exceptions.txt; slight +deviations of the current exceptions cause warnings, whereas large +ones cause practracker to fail. + +For usage information, run "practracker.py --help". diff --git a/scripts/maint/practracker/practracker.py b/scripts/maint/practracker/practracker.py index 6483b88da..73e4cb3e8 100755 --- a/scripts/maint/practracker/practracker.py +++ b/scripts/maint/practracker/practracker.py @@ -7,7 +7,8 @@ Go through the various .c files and collect metrics about them. If the metrics violate some of our best practices and they are not found in the optional exceptions file, then log a problem about them.
-We currently do metrics about file size, function size and number of includes. +We currently do metrics about file size, function size and number of includes, +for C files and headers.
practracker.py should be run with its second argument pointing to the Tor top-level source directory like this: @@ -143,8 +144,12 @@ HEADER="""\ # # There are three kinds of problems that we recognize right now: # function-size -- a function of more than {MAX_FUNCTION_SIZE} lines. -# file-size -- a file of more than {MAX_FILE_SIZE} lines. -# include-count -- a file with more than {MAX_INCLUDE_COUNT} #includes. +# file-size -- a C file of more than {MAX_FILE_SIZE} lines, or an H +# file with more than {MAX_H_FILE_SIZE} lines. +# include-count -- a C file with more than {MAX_INCLUDE_COUNT} #includes, + or an H file with more than {MAX_H_INCLUDE_COUNT} #includes. +# dependency-violation -- a file includes a header that it should +# not, according to an advisory .may_include file. # # Each line below represents a single exception that practracker should # _ignore_. Each line has four parts: