Add a type and version header to the fallback directory mirror file

This helps external parsers like stem and Relay Search.

Implements ticket 24725.

diff --git a/changes/ticket24725 b/changes/ticket24725
new file mode 100644 (file)
index 0000000..2fe1848
--- /dev/null
+++ b/changes/ticket24725
@@ -0,0 +1,4 @@
+  o Minor features (fallback directory mirrors):
+    - Add a type and version header to the fallback directory mirror file.
+      This helps external parsers like stem and Relay Search.
+      Implements ticket 24725.

diff --git a/scripts/maint/updateFallbackDirs.py b/scripts/maint/updateFallbackDirs.py
index cf96fc308fbb233c36b3e1bef0078e5d80603a25..7869d942c1ff065bcef3fdde9ec4ff53fda58229 100755 (executable)
--- a/scripts/maint/updateFallbackDirs.py
+++ b/scripts/maint/updateFallbackDirs.py
@@ -68,6 +68,15 @@ except ImportError:
 
 ## Top-Level Configuration
 
+# We use semantic versioning: https://semver.org
+# In particular:
+# * major changes include removing a mandatory field, or anything else that
+#   would break an appropriately tolerant parser,
+# * minor changes include adding a field,
+# * patch changes include changing header comments or other unstructured
+#   content
+FALLBACK_FORMAT_VERSION = '2.0.0'
+
 # Output all candidate fallbacks, or only output selected fallbacks?
 OUTPUT_CANDIDATES = False
 
@@ -2124,6 +2133,9 @@ def list_fallbacks(whitelist, blacklist):
   """ Fetches required onionoo documents and evaluates the
       fallback directory criteria for each of the relays """
 
+  print "/* type=fallback */"
+  print ("/* version={} */"
+         .format(cleanse_c_multiline_comment(FALLBACK_FORMAT_VERSION)))
   logging.warning('Downloading and parsing Onionoo data. ' +
                   'This may take some time.')
   # find relays that could be fallbacks