[tor-commits] [tor/master] Add a type and version header to the fallback directory mirror file

[nickm at torproject.org]

commit 8d226a2c7b78dc1db998cb6ba075c0170b7cc521
Author: teor <teor2345 at gmail.com>
Date:   Sun Dec 24 11:36:45 2017 +1100

    Add a type and version header to the fallback directory mirror file
    
    This helps external parsers like stem and Relay Search.
    
    Implements ticket 24725.
---
 changes/ticket24725                 |  4 ++++
 scripts/maint/updateFallbackDirs.py | 12 ++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/changes/ticket24725 b/changes/ticket24725
new file mode 100644
index 000000000..2fe1848ab
--- /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 cf96fc308..7869d942c 100755
--- 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