Document new practracker violation types, and add a practracker readme

Closes ticket 31476.

diff --git a/Makefile.am b/Makefile.am
index d3cce3934d41bbf9bd833cf9dcbee4cf546ee2be..0800497dc21d7cdd51d1273d10becb9ac0287940 100644 (file)
--- 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 (file)
index 0000000..d2ad822
--- /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 6483b88da137311e0b3c75a9203e9acc1d7bcc03..73e4cb3e8b7c707642b69055d5808a6ea8c5db54 100755 (executable)
--- 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: