Re: [PATCH] pack-protocol: mention and point to docs for protocol v2
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. You can call it Documentation/technical/git-protocol.txt, since from the context it's clear that this is going over the wire. 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
Re: [PATCH] pack-protocol: mention and point to docs for protocol v2
On 07/24, Junio C Hamano wrote: > Brandon Williams 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
Brandon Williams 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
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 `=` 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? 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
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
[PATCH] pack-protocol: mention and point to docs for protocol v2
Signed-off-by: Brandon Williams --- 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 `=` 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 +information on protocol version 2. Git Transport - -- 2.18.0.233.g985f88cf7e-goog