[tor-bugs] #23391 [Metrics/Metrics website]: Add changes section to Tor bridge descriptors specification

[Tor Bug Tracker & Wiki]

#23391: Add changes section to Tor bridge descriptors specification
-------------------------------------+------------------------------
 Reporter:  karsten                  |          Owner:  metrics-team
     Type:  enhancement              |         Status:  needs_review
 Priority:  Medium                   |      Milestone:
Component:  Metrics/Metrics website  |        Version:
 Severity:  Normal                   |     Resolution:
 Keywords:                           |  Actual Points:
Parent ID:                           |         Points:
 Reviewer:                           |        Sponsor:
-------------------------------------+------------------------------

Comment (by karsten):

 Replying to [comment:3 iwakeh]:
 > Yes, it is important to have such a change description/listing.
 >
 > To have a more complete changelog more items should be included.  From
 the simple
 [https://gitweb.torproject.org/collector.git/log/?qt=grep&q=sani git
 search]:

 Ah, I guess we'll first have to decide what should go into this changes
 section. My plan was to only include changes to the specification, that
 is, changes to the way how we're modifying original bridge descriptors
 when sanitizing them. Now, some of the changes you suggest don't affect
 the specification but only the implementation. Let me explain using the
 first example:

 > *     Retain padding-counts lines when sanitizing descriptors.
 Karsten Loesing 2017-05-11

 These "padding-counts" lines never showed up in bridge descriptors until a
 few days before this commit. And when they first showed up, CollecTor
 rejected the entire descriptor, printed out a warning, and continued with
 the next descriptor. After we checked that these lines can go in without
 change, this commit simply made sure they're copied over.

 In summary, whenever an original bridge descriptors did not contain such a
 line, the sanitized descriptor didn't either. And if the original
 descriptor contained this line, the sanitized one did as well. That's also
 why we didn't bump the version number. There was no change to the
 specification.

 This is different for changes where we're modifying line contents, adding
 lines that didn't exist before, truncating lines, or even removing lines
 entirely. Those are all changes that would require a version number bump
 and probably an entry in this new changes section.

 Maybe think of it in a different way: If our implementation would default
 to accepting unknown lines and only touch lines that we modify in the
 sanitizing process, these new lines in original descriptors would not even
 produce a Git commit. I'm not saying it's a better approach, it's just an
 attempt to distinguish the two types of changes.

 > *     Retain hidserv-* lines when sanitizing descriptors.     Karsten
 Loesing 2016-11-23

 Same.

 > *     Sanitize TCP ports in bridge descriptors.       Karsten Loesing
 2016-09-18

 This one is in my list, too.

 > *     Sanitize bridge descriptors with ed25519 lines. Karsten Loesing
 2015-06-13

 In my list, too.

 > *     Parse "published" lines from bridge statuses.   Karsten Loesing
 2014-10-13

 This one is tricky. We did write such a line ourselves before, and with
 this change we're copying that line from the original descriptor. I guess
 we should add it, even though it didn't lead to a version number bump.

 > *     Clarify ntor-onion-key lines and @type versions.        Karsten
 Loesing 2014-06-10

 That's just a documentation patch.

 > *       ...
 >
 > CollecTor's
 [https://gitweb.torproject.org/collector.git/tree/CHANGELOG.md changelog]
 is also a source for change info.
 > Maybe, there's a way to automate the list?  All bridge desc sanitation
 related changes in a release tag without test related commits ...
 > Well, at least a source for adding historical changes manually.

 Maybe we can use this list as source for discussion what should go into
 changes and what should not? Some of these changes are tricky and require
 per-case inspection and possibly discussion.

 Would you want to create such a list?

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