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 `<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
