From: Jonathan Nieder Date: Tue, 24 Jul 2018 04:52:33 GMT Subject: Re: [PATCH] pack-protocol: mention and point to docs for protocol v2 Message-ID: <20180724045233.GB208393@aiede.svl.corp.google.com> In-Reply-To: <20180723174807.28903-1-bmwill@google.com> Hi, Brandon Williams wrote: > --- a/Documentation/technical/pack-protocol.txt > +++ b/Documentation/technical/pack-protocol.txt > @@ -50,7 +50,8 @@ Each Extra Parameter takes the form of `=` or ``. > > Servers that receive any such Extra Parameters MUST ignore all > unrecognized keys. Currently, the only Extra Parameter recognized is > -"version=1". > +"version" with a vlue of '1' or '2'. See protocol-v2.txt for more value? > +information on protocol version 2. Thanks. Some thoughts on other parts of this document that may need updating: - the whole document assumes that 0 and 1 are the only protocol versions. E.g. the discussion of the version number line in the response when "version=1" is sent as an Extra Paramter should probably apply to version 2, too. - because the document was written before protocol v2, it describes the more complicated v1 that many readers shouldn't have to care about - there is no one document that describes v2 in a self contained way, since protocol-v2.txt makes reference to protocol v1. - the description of pkt-line format in protocol-common.txt is missing a discussion of delim-pkt. Not about this patch, but I wonder if an organization along the following lines would make sense? 1. Rename pack-protocol.txt to protocol-v1.txt. Rename protocol-v2.txt to pack-protocol.txt. 2. Make pack-protocol.txt self-contained, and remove any redundant sections from protocol-v1.txt. 3. Add a new protocol-v2.txt that briefly describes the benefits and highlights of protocol v2, referring to pack-protocol.txt for details. That way, newcomers of the future could read pack-protocol.txt and quickly glean the main protocol in (then) current use. What do you think? Thanks, Jonathan