[tor-commits] [tor/master] dirvote: Update the comments for required protocols

[nickm at torproject.org]

commit ed1ee2001f78549454b6196b932ae9bb4d0fdcba
Author: teor <teor at torproject.org>
Date:   Fri Feb 14 12:49:38 2020 +1000

    dirvote: Update the comments for required protocols
    
    Add doxygen comments to the new recommended and required subprotocol
    version strings.
    
    Add a warning to the required protocol documentation, because requiring
    the wrong protocols can break the tor network. Also reference
    proposal 303: When and how to remove support for protocol versions.
    
    Part of 33285.
---
 src/feature/dirauth/dirvote.h | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/src/feature/dirauth/dirvote.h b/src/feature/dirauth/dirvote.h
index cf9f1370e..305094aa4 100644
--- a/src/feature/dirauth/dirvote.h
+++ b/src/feature/dirauth/dirvote.h
@@ -230,17 +230,32 @@ char *networkstatus_get_detached_signatures(smartlist_t *consensuses);
 STATIC microdesc_t *dirvote_create_microdescriptor(const routerinfo_t *ri,
                                                    int consensus_method);
 
-/* These are hardwired, to avoid disaster. */
+/** The recommended relay protocols for this authority's votes.
+ * Recommending a new protocol causes old tor versions to log a warning.
+ */
 #define DIRVOTE_RECCOMEND_RELAY_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"
+/** The recommended client protocols for this authority's votes.
+ * Recommending a new protocol causes old tor versions to log a warning.
+ */
 #define DIRVOTE_RECCOMEND_CLIENT_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"
 
+/** The required relay protocols for this authority's votes.
+ * WARNING: Requiring a new protocol causes old tor versions to shut down.
+ *          Requiring the wrong protocols can break the tor network.
+ * See Proposal 303: When and how to remove support for protocol versions.
+ */
 #define DIRVOTE_REQUIRE_RELAY_PROTO \
   "Cons=1 Desc=1 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=3-4 Microdesc=1 Relay=1-2"
+/** The required relay protocols for this authority's votes.
+ * WARNING: Requiring a new protocol causes old tor versions to shut down.
+ *          Requiring the wrong protocols can break the tor network.
+ * See Proposal 303: When and how to remove support for protocol versions.
+ */
 #define DIRVOTE_REQUIRE_CLIENT_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"