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

[Jeff King <peff@peff.net>]

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

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