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

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

[Brandon Williams]

Signed-off-by: Brandon Williams <bmwill@google.com>
---
 Documentation/technical/pack-protocol.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 7fee6b780a..25acd9edb1 100644
--- 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
+information on protocol version 2.
 
 Git Transport
 -------------
-- 
2.18.0.233.g985f88cf7e-goog

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

[Jonathan Nieder]

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

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

[Brandon Williams]

On 07/23, Jonathan Nieder wrote:
> 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?

yep, missed a letter.

> 
> > +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?

I dislike the idea of renaming protocol-v2.txt to pack-protocol.txt.  I
agree that we should probably have protocol-v1 broken out into its own
file, taking the parts from pack-protocol.txt, but what really should
happen is that pack-protocol.txt could describe the basics of the wire
protocol (pkt-lines, the format of the various transports, etc) and then
refer to the protocol-v{1,2}.txt documents themselves.

-- 
Brandon Williams

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

[Junio C Hamano]

Brandon Williams <bmwill@google.com> writes:

>> 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?
>
> I dislike the idea of renaming protocol-v2.txt to pack-protocol.txt.  I
> agree that we should probably have protocol-v1 broken out into its own
> file, taking the parts from pack-protocol.txt, but what really should
> happen is that pack-protocol.txt could describe the basics of the wire
> protocol (pkt-lines, the format of the various transports, etc) and then
> refer to the protocol-v{1,2}.txt documents themselves.

WRT the naming, are we happy with the idea of (1) pretending that
when we say 'protocol', there is nothing but the on-the-wire
pkt-line protocol (i.e. that is why we call "protocol-v2" without
giving any other adjective---are we sure we won't have need for any
other kind of protocol?) and (2) tying the "pack" ness to the name of
on-the-wire pkt-line protocol (i.e. that is where the name of the
original pack-protocol.txt came from, as it started only for the
packfile transfer---are we happy to keep newer protocols tied to
"pack" the same way)?

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

[Brandon Williams]

On 07/24, Junio C Hamano wrote:
> Brandon Williams <bmwill@google.com> writes:
> 
> >> 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?
> >
> > I dislike the idea of renaming protocol-v2.txt to pack-protocol.txt.  I
> > agree that we should probably have protocol-v1 broken out into its own
> > file, taking the parts from pack-protocol.txt, but what really should
> > happen is that pack-protocol.txt could describe the basics of the wire
> > protocol (pkt-lines, the format of the various transports, etc) and then
> > refer to the protocol-v{1,2}.txt documents themselves.
> 
> WRT the naming, are we happy with the idea of (1) pretending that
> when we say 'protocol', there is nothing but the on-the-wire
> pkt-line protocol (i.e. that is why we call "protocol-v2" without
> giving any other adjective---are we sure we won't have need for any
> other kind of protocol?) and (2) tying the "pack" ness to the name of
> on-the-wire pkt-line protocol (i.e. that is where the name of the
> original pack-protocol.txt came from, as it started only for the
> packfile transfer---are we happy to keep newer protocols tied to
> "pack" the same way)?

If so I suggest we move away from the term "pack" protocol.  Mostly
because maybe at some future date we don't only want to communicate to
transfer packs.  So at the risk of bikeshedding (and because naming is
hard) I think we should begin talking about the over the wire protocol
as just that, the "wire protocol" or if we need to be more explicit the
"git wire protocol". Thoughts?

-- 
Brandon Williams

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

[Jonathan Nieder]

Brandon Williams wrote:

> If so I suggest we move away from the term "pack" protocol.  Mostly
> because maybe at some future date we don't only want to communicate to
> transfer packs.  So at the risk of bikeshedding (and because naming is
> hard) I think we should begin talking about the over the wire protocol
> as just that, the "wire protocol" or if we need to be more explicit the
> "git wire protocol". Thoughts?

Sounds fine to me.

<bikeshed>You can call it Documentation/technical/git-protocol.txt,
since from the context it's clear that this is going over the
wire.</bikeshed>

The main point of what Junio said is that it means the docs should
treat "git upload-archive" instead same way as "git upload-pack" and
"git receive-pack", instead of artifically separating the archive
file-oriented and the pack-oriented parts of the protocol.

Thanks,
Jonathan