Re: [PATCH v3 1/2] name-rev: deprecate --stdin in favor of --annotate-text

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jan 4, 2022, 19:38 UTC
Message-ID: <CAPig+cRUQA_G_sLi4Q_F4ZhHkhEFKT-an4LuOpbTJ9bDuZLjog@mail.gmail.com>
In-Reply-To: <77e18a78-ddfe-0337-deaf-bb9dfb63a495@iee.email>

On Tue, Jan 4, 2022 at 10:32 AM Philip Oakley <philipoakley@iee.email> wrote:

Show 20 quoted lines

> On 03/01/2022 14:47, John Cai via GitGitGadget wrote:
> > From: John Cai <johncai86@gmail.com>
> >  --stdin::
> > +     This option is deprecated in favor of 'git name-rev --annotate-stdin'.
> > +     They are functionally equivalent.
> > +
> > +--annotate-stdin::
> >       Transform stdin by substituting all the 40-character SHA-1
> >       hexes (say $hex) with "$hex ($rev_name)".  When used with
> >       --name-only, substitute with "$rev_name", omitting $hex
> > -     altogether.  Intended for the scripter's use.
> > +     altogether.
>
> Is there a preferred order for the old/new variant documentation?
>
> It struck me that the docs should offer the new (now 'correct') variant
> first.
>
> I didn't see anything about deprecation in the CodingGuidlines or
> SubmittingPatches (only a quick search though)

In other cases, we've demoted the deprecated option to a tiny blurb at the end of the description of the option which replaces it so that the deprecated option is no longer given a place of prominence but can still be found with a search in case someone runs across it somewhere and wants to learn about it.

    --annotate-stdin::
        Transform stdin by substituting all the 40-character SHA-1
        hexes (say $hex) with "$hex ($rev_name)".  When used with
        --name-only, substitute with "$rev_name", omitting $hex
        altogether. --stdin is a deprecated synonym.