Re: [PATCH] pack-protocol: mention and point to docs for protocol v2

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jul 24, 2018, 04:52 UTC
Message-ID: <20180724045233.GB208393@aiede.svl.corp.google.com>
In-Reply-To: <20180723174807.28903-1-bmwill@google.com>

Hi,

Brandon Williams wrote:

Show 8 quoted lines

> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -50,7 +50,8 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
>  
>  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