pack-protocol: mention and point to docs for protocol v2
PATCH 1/1 pack-protocol: mention and point to docs for protocol v2
--- Documentation/technical/pack-protocol.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/technical/pack-protocol.txt +2 -1
@@ -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 -------------
Signature · 1 line
2.18.0.233.g985f88cf7e-goog
Hi,
Documentation/technical/pack-protocol.txt Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. · line 53
Quoted 8 lines · Brandon Williams
Documentation/technical/pack-protocol.txt +1
-1@@ -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?
Documentation/technical/pack-protocol.txt Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. · line 54
Quoted 1 line
Documentation/technical/pack-protocol.txt +1
-0+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
Quoted 8 lines · Jonathan Nieder
Hi,
Quoted 4 lines · Brandon Williams
Documentation/technical/pack-protocol.txt +0
-0@@ -50,7 +50,8 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
Quoted 6 lines
Documentation/technical/pack-protocol.txt Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. · line 53
Quoted 4 lines
Documentation/technical/pack-protocol.txt +1
-1Servers 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 morevalue?
yep, missed a letter.
Quoted 29 lines
Documentation/technical/pack-protocol.txt Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. · line 54
Quoted 2 lines
Documentation/technical/pack-protocol.txt +1
-0+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.
Quoted 8 lines
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.
Signature · 1 line
Brandon Williams
Quoted 16 lines · Brandon Williams
Quoted 16 lines
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.
Quoted 8 lines
Quoted 1 line
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)?
Quoted 27 lines · Junio C Hamano
Quoted 16 lines · Brandon Williams
Quoted 16 lines
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.
Quoted 8 lines
Quoted 1 line
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.
Quoted 9 lines
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?
Signature · 1 line
Brandon Williams
Quoted 6 lines · Brandon Williams
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