Re: [PATCH 4/8] Documentation: order protocol v2 sections

From: Junio C Hamano <gitster@pobox.com>
Date: May 29, 2020, 23:32 UTC
Message-ID: <xmqqa71qxqoy.fsf@gitster.c.googlers.com>
In-Reply-To: <7a2e9c3c5994fc155eb6a40f039cf2298957fa6c.1590789428.git.jonathantanmy@google.com>

Jonathan Tan <jonathantanmy@google.com> writes:

> The current C Git implementation expects Git servers to follow a
> specific order of sections when transmitting protocol v2 responses, but
> this is not explicit in the documentation. Make the order explicit.

Thanks. Are we breaking other people's implementation, or is this the order all reimplementations of Git currently follow, so this is purely an preemptive safety measure?

Show 49 quoted lines

> Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
> ---
>  Documentation/technical/protocol-v2.txt | 18 ++++++++----------
>  1 file changed, 8 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt
> index 3996d70891..ef7514a3ee 100644
> --- a/Documentation/technical/protocol-v2.txt
> +++ b/Documentation/technical/protocol-v2.txt
> @@ -327,11 +327,11 @@ included in the client's request:
>  
>  The response of `fetch` is broken into a number of sections separated by
>  delimiter packets (0001), with each section beginning with its section
> -header.
> +header. Most sections are sent only when the packfile is sent.
>  
> -    output = *section
> -    section = (acknowledgments | shallow-info | wanted-refs | packfile)
> -	      (flush-pkt | delim-pkt)
> +    output = acknowledgements flush-pkt |
> +	     [acknowledgments delim-pkt] [shallow-info delim-pkt]
> +	     [wanted-refs delim-pkt] packfile flush-pkt
>  
>      acknowledgments = PKT-LINE("acknowledgments" LF)
>  		      (nak | *ack)
> @@ -353,9 +353,10 @@ header.
>  	       *PKT-LINE(%x01-03 *%x00-ff)
>  
>      acknowledgments section
> -	* If the client determines that it is finished with negotiations
> -	  by sending a "done" line, the acknowledgments sections MUST be
> -	  omitted from the server's response.
> +	* If the client determines that it is finished with negotiations by
> +	  sending a "done" line (thus requiring the server to send a packfile),
> +	  the acknowledgments sections MUST be omitted from the server's
> +	  response.
>  
>  	* Always begins with the section header "acknowledgments"
>  
> @@ -406,9 +407,6 @@ header.
>  	  which the client has not indicated was shallow as a part of
>  	  its request.
>  
> -	* This section is only included if a packfile section is also
> -	  included in the response.
> -
>      wanted-refs section
>  	* This section is only included if the client has requested a
>  	  ref using a 'want-ref' line and if a packfile section is also