On Tue, Jan 4, 2022 at 10:32 AM Philip Oakley <philipoakley@iee.email> wrote:
> On 03/01/2022 14:47, John Cai via GitGitGadget wrote:
> > From: John Cai <johncai86@xxxxxxxxx>
> > --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.
