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

> 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