Document how to test the hard-coded fallback list

diff --git a/scripts/maint/fallback.whitelist b/scripts/maint/fallback.whitelist
index 06456c62060d9112e207b88f3ad9984befb940d7..ce45f0dc466a8f2832535f759d74c9c7290a138b 100644 (file)
--- 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 464d8476f07a0c6ece300354f76195e35b63ac94..7fcb3658c469d295a4a5904ba23b9ea9534b44c0 100755 (executable)
--- 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)