Re: [PATCH v2] protocol-capabilities.txt: document symref

From: Jeff King <peff@peff.net>
Date: Feb 14, 2019, 03:56 UTC
Message-ID: <20190214035602.GA7209@sigill.intra.peff.net>
In-Reply-To: <cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon@google.com>

On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote:

Show 18 quoted lines

> ---
> Range-diff against v1:
> 1:  4ffb11ff77 ! 1:  cb1b2834b7 protocol-capabilities.txt: document symref
>     @@ -12,6 +12,17 @@
>       diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
>       --- a/Documentation/technical/protocol-capabilities.txt
>       +++ b/Documentation/technical/protocol-capabilities.txt
>     +@@
>     + Git Protocol Capabilities
>     + =========================
>     + 
>     ++NOTE: this document describes capabilities for versions 0 and 1 of the pack
>     ++protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
>     ++doc.
>     ++
>     + Servers SHOULD support all capabilities defined in this document.
>     + 
>     + On the very first line of the initial server response of either

I think this makes sense. I wondered to what degree the v2 protocol doc may say "...and you can use capabilities from protocol-capabilities.txt here". But it doesn't. It newly lists the capabilities, which makes this paragraph the right thing to say.

It does mean that if we teach v1 a new capability, we'll have to document it in both places. But moving forward, we'd hopefully not be doing that too often (I haven't seen talk of flipping the v2 switch yet by default, but obviously that's where we want to end up).

I probably would have put this in its own patch, but barring that we should probably at least mention in the commit message what this paragraph is doing here.

-Peff