[tor-bugs] #5651 [Metrics Utilities]: Annotation header with descriptor types

[Tor Bug Tracker & Wiki]

#5651: Annotation header with descriptor types
-------------------------------+--------------------------------------------
 Reporter:  atagar             |          Owner:     
     Type:  enhancement        |         Status:  new
 Priority:  normal             |      Milestone:     
Component:  Metrics Utilities  |        Version:     
 Keywords:                     |         Parent:     
   Points:                     |   Actualpoints:     
-------------------------------+--------------------------------------------

Comment(by karsten):

 How about we add an annotation line `@type descriptor-type major.minor` as
 the new first line of a descriptor?

 The `@type` part would be the same for all descriptor type annotations we
 add, and the `descriptor-type major.minor` part would be something we
 agree on for each descriptor type.  `major` would be the version of the
 format produced by Tor or whichever tool produces the descriptor and
 `minor` would be the version of the format that metrics-db makes of it.

 We might want to reserve `@type` in dir-spec.txt, or we may run into
 trouble once Tor writes such an annotation itself.  Maybe that means we'll
 have to pick something more specific than `@type`, hmm.  The list of
 descriptor types and versions would go on the
 [https://metrics.torproject.org/formats.html metrics formats] page.

 There are three kinds of descriptors: a) descriptors produced by Tor that
 we leave unchanged, b) descriptors produced by Tor that we sanitize, c)
 descriptors produced by Tor services like BridgeDB, GetTor, Tor Check, or
 Torperf which we may also reformat.

 The descriptors in a) could use the version numbers taken from dir-
 spec.txt where they were first described; we'll want to ask nickm/arma
 whether the version numbers we choose make sense.  In theory, we don't
 mess with these descriptors at all, but just in case we have to, we can
 change the `.0` part to reflect that:

  - `@type server-descriptor 1.0`
  - `@type extra-info 1.0`
  - `@type directory 1.0`
  - `@type network-status 2.0`
  - `@type network-status-consensus 3.0`
  - `@type network-status-vote 3.0`

 The descriptors in b) should probably have version numbers based on dir-
 spec.txt ''and'' our sanitizing approach.  The `.0` part would be
 incremented whenever we change something in the sanitizing approach:

  - `@type bridge-network-status 1.0`
  - `@type bridge-server-descriptor 1.0`
  - `@type bridge-extra-info 1.0`

 The descriptors in c) are not based on dir-spec.txt and should therefore
 start at version 1, plus they should have a `.0` part that we can
 increment whenever we change their format.

  - `@type torperf 1.0`
  - `@type bridge-pool-assignment 1.0`
  - `@type gettor 1.0`
  - `@type tordnsel 1.0`

-- 
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/5651#comment:1>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online