[tor-dev] Dusting off dir-spec.txt

[Karsten Loesing]

On 1/6/14 6:04 PM, Nick Mathewson wrote:
> On Sun, Jan 5, 2014 at 2:56 AM, Karsten Loesing <karsten at torproject.org> wrote:
>> [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,
>  [...]
>> Would you accept patches making these changes?
> 
> I'm okay with re-ordering for readability and maintainability, and the
> order you describe seems okay.  I think that we'll need more changes
> for readability, but there's no reason to let the perfect be the enemy
> of the good here.

So, I finished a first revision in my branch reorder-dirspec:

https://gitweb.torproject.org/user/karsten/torspec.git/shortlog/refs/heads/reorder-dirspec

I'm counting 35 commits, so I really tried to keep changes in each
commit small.

Here are the guidelines that I tried to follow:

- There's supposed to be one section per role in the directory protocol
(client, authority, cache, client) with one subsection per operation
performed by this role.  If necessary, subsubsections help structure
more complex operations.

- Changes are ordered from the top of the document to the bottom.
There's typically one commit (or commit set) for every changed section
or subsection.

- For every change that moves more than a few lines of text, there are
typically three commits: the first commit only moves text, the second
commit only fixes references, and the third commit edits content.

Want to have a look?

(Let me know if you prefer this review to happen in a ticket rather than
here.)

All the best,
Karsten