Subject: Re: [PATCH 8/8] Documentation/git-config: update to new-style syntax

From: Patrick Steinhardt <[email-masked]>
Date: Thu, 7 Mar 2024 08:33:36 +0100

On Thu, Mar 07, 2024 at 01:57:41AM -0500, Eric Sunshine wrote:
> On Wed, Mar 6, 2024 at 6:32 AM Patrick Steinhardt <[email-masked]> wrote:
> > Update our documentation of git-config(1) to stop mentioning the old
> > syntax while starting to mention the new syntax. Remove the help
> > mismatch in t0450 so that we start to ensure that the manpage and
> > builtin synopsis match.
> > [...]
> > Signed-off-by: Patrick Steinhardt <[email-masked]>
> 
> I'd like to push back on the part of this patch which completely
> eradicates mention of the old syntax. Doing so makes it difficult for
> people to figure out the meaning of git-config commands which they run
> across in blogs and existing tooling. For instance, the following
> recommendation is commonly encountered in the wild:
> 
>     git config --global user.name "Your Name"
>     git config --global user.email "[email-masked]"
> 
> Typically, we instead retain the old syntax (or options or whatever)
> in the documentation so that people who want to learn can learn, but
> we rewrite it to make it clear that it is deprecated, and explicitly
> point the reader at the modern replacement command or option (or
> whatever).
> 
> So, perhaps you can have a SYNOPSIS section for the deprecated usage,
> as well as a "DEPRECATED OPTIONS" section (or such), so that we don't
> leave readers entirely in the dark.

Fair point indeed. I will update this patch accordingly, thanks!

Patrick