commit 5b3741e05ac82cbe99942cffdc5662bd53c783dc
parent cc48eff2d3b07a8dd2f621f09217ba29b4e6771c
Author: Nick Mathewson <nickm@torproject.org>
Date: Wed, 21 Aug 2019 10:00:05 -0400
Document new practracker violation types, and add a practracker readme
Closes ticket 31476.
Diffstat:
3 files changed, 30 insertions(+), 3 deletions(-)
diff --git 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
@@ -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
@@ -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:
