[Re-sending, because my first attempt apparently got lost somewhere. Apologies if gets found and this is now a duplicate.]
Hi devs, hi dir-spec.txt authors,
when I reviewed the open proposals related to the directory protocol, I wondered how to integrate the proposed changes into dir-spec.txt. For example, status opinions (proposal 147) are going to add a new variant of the status data format and a new operation that makes authorities produce and exchange opinions at some point in the voting process.
I also thought back when I wrote the patch to add microdescriptors to the spec and remembered that I had a hard time finding the right places to add things.
So, here's my question: can we reorder a few things in dir-spec.txt to make it easier to read and easier to extend? (To be clear, I'm happy to submit patches for this, I'm just asking if patches are welcome.)
In particular, I'd want to start by making the following changes (if you need a table of contents, here's how I generated mine: `grep -Ev "^ |^$|XXXX" dir-spec.txt | less`):
Sections 3 ("Formats produced by directory authorities") and 4 ("Directory server operation") apparently started out by separating passive parts (data formats) from active parts (operations). But then 3.4 ("Assigning flags in a vote") and 3.5 ("Computing a consensus from a set of votes") broke this abstraction.
One way to fix this would be to move the two mentioned subsections 3.4 and 3.5 to Section 4. Though, personally I'm not a big fan of the passive-active separation, because the description of passive parts implies a lot about how they're going to be used. And then we end up describing things twice, once implicitly and once explicitly.
The better fix, IMHO, would be to turn Section 3 into "Directory authority operation and formats" and Section 4 into "Directory cache operation". Section 3 would specify operations in causal order (not sure if this the right term) and specify data formats together with the operation that generates them: - "creating key certificates", - "accepting router descriptors and extra-info documents", - "computing microdescriptors", - "exchanging votes", - "downloading missing certificates", - "downloading router descriptors and extra-info documents", - "computing the consensus", - "computing consensus flavors", - "exchanging detached signatures", and - "publishing the signed consensus".
Section 4 would then only contain the subsections from the current Section 4 that are relevant for caches. In cases where cache operations are equivalent or similar to authority operations, there would be a simple reference to the earlier section.
Also on the top-level of sections, I'd want to merge Sections 5 ("Client operation: downloading information") and 6 ("Using directory information") into a single section "Client operation".
Would you accept patches making these changes?
All the best, Karsten