torspec: Document the new "flag-thresholds" item in votes

changed milestone to %Tor: 0.2.4.x-final

added component::core tor/tor milestone::Tor: 0.2.4.x-final parent::8151 priority::medium resolution::fixed status::closed tor-spec type::defect labels

See branch bug8165 in https://git.torproject.org/user/asn/torspec.git.

Trac:
Status: new to needs_review

Looks good. Some tweaks: https://gitweb.torproject.org/user/karsten/torspec.git/shortlog/refs/heads/bug8165

Please add a formal description of the Thresholds attribute. At present there's not enough information to know what the line has. My first thought was 'oh, they're probably just space separated flags', then 'hm, maybe they're key= mappings?' - both were wrong so I was lucky that Karsten had an example on #8164 (moved).

Something like the following might work...

"flag-thresholds" SP THRESHOLDS NL

[At most once for votes; does not occur in consensuses.]

THRESHOLDS = THRESHOLD | THRESHOLD SP THRESHOLDS
THRESHOLD = THRESHOLD_KEY "=" THRESHOLD_VALUE
THRESHOLD_KEY = [A-Za-z0-9]+
THRESHOLD_VALUE = [A-Za-z0-9%]+

I suspect that what we really want for THRESHOLD_VALUE is 'ArgumentChar except WS' though I'm not entirely sure how we'd define that.

Also, can there be duplicate THRESHOLD_KEYs? If so then what does it mean?

Correction, THRESHOLD_KEY should probably be 'KeywordChar+'.

Even better, can we ensure numeric values with an optional '%'?

THRESHOLD_VALUE = None..None+[%]?

If so then libraries like stem and metrics-lib can provide a nicer API to users.

Seems like Tor should stop including the %. It doesn't help and seems to hurt.

Stem and metrics-lib could simply divide threshold values with a trailing % by 100. No need to change the line format, IMO. In fact, the format with % is already in a released version, so please don't change it.

To be clear, I'm not suggesting changing where the decimal place goes. Just dropping the extraneous characters that no parsers are using anyway.

Still, you'd change the format by doing so. Parsers have to support all existing formats, with and without the % sign, because they have to handle archived votes, too.

Okay, I've merged and tweaked it a little. If it's wrong somehow, more patches are welcome.

Trac:
Milestone: N/A to Tor: 0.2.4.x-final
Status: needs_review to closed
Resolution: N/A to fixed

Consistently use tor-spec across all tickets (add tor-spec).

Trac:
Keywords: N/A deleted, tor-spec added

Consistently use tor-spec across all tickets (remove torspec).

Trac:
Keywords: torspec deleted, N/A added

closed

moved to tpo/core/tor#8165 (closed)