Document how to test the hard-coded fallback list

2 files changed, 19 insertions, 0 deletions

diff --git a/scripts/maint/fallback.whitelist b/scripts/maint/fallback.whitelist
index 06456c6206..ce45f0dc46 100644
--- a/scripts/maint/fallback.whitelist
+++ b/scripts/maint/fallback.whitelist
@@ -8,6 +8,21 @@
 # it, and vice versa, otherwise they don't match.
 # (The blacklist overrides the whitelist.)
 
+# To replace this list with the hard-coded fallback list (for testing), use
+# a command similar to:
+#   cat src/or/fallback_dirs.inc | grep \" | grep -v weight | tr -d '\n' | \
+#   sed 's/"" / /g' | sed 's/""/"/g' | tr \" '\n' | grep -v '^$' \
+#   > scripts/maint/fallback.whitelist
+#
+# When testing before a release, exclusions due to changed details will result
+# in a warning, unless the IPv4 address or port change happened recently.
+# Then it is only logged at info level, as part of the eligibility check.
+# Exclusions due to stability also are only shown at info level.
+#
+# Add the number of selected, slow, and excluded relays, and compare that to
+# the number of hard-coded relays. If it's less, use info-level logs to find
+# out why each of the missing relays was excluded.
+
 # If a relay operator wants their relay to be a FallbackDir,
 # enter the following information here:
 # <IPv4>:<DirPort> orport=<ORPort> id=<ID> [ ipv6=<IPv6>:<IPv6 ORPort> ]
diff --git a/scripts/maint/updateFallbackDirs.py b/scripts/maint/updateFallbackDirs.py
index 464d8476f0..7fcb3658c4 100755
--- a/scripts/maint/updateFallbackDirs.py
+++ b/scripts/maint/updateFallbackDirs.py
@@ -1909,6 +1909,10 @@ def list_fallbacks():
   prefilter_fallbacks = copy.copy(candidates.fallbacks)
 
   # filter with the whitelist and blacklist
+  # if a relay has changed IPv4 address or ports recently, it will be excluded
+  # as ineligible before we call apply_filter_lists, and so there will be no
+  # warning that the details have changed from those in the whitelist.
+  # instead, there will be an info-level log during the eligibility check.
   initial_count = len(candidates.fallbacks)
   excluded_count = candidates.apply_filter_lists()
   print candidates.summarise_filters(initial_count, excluded_count)