Subject: Re: [RFC PATCH] docs: document upcoming breaking changes

From: Junio C Hamano <[email-masked]>
Date: Wed, 08 May 2024 07:58:24 -0700

Patrick Steinhardt <[email-masked]> writes:

>> Another thing we may want to describe in such a document is what we
>> do not want to drop and why, even when a new way that is a superset
>> is available, which would give newbies with a natural "why don't we
>> force everybody including the old timers to adopt new ways" question
>> a reasonable answer.
>
> Okay, I see how that may make sense for some parts. I guess one of the
> motivations here is things like git-checkout(1) and git-switch(1) /
> git-restore(1)?

Anything that we initially think it may make sense to remove but
turns out that they are so ingrained in workflows that may lead some
users to stick to pre-3.0 version.  As this is a living document,
instead of removing some ideas that are "voted down", recording the
reason why we voted it down would make sense.  Checkout and annotate
are the ones that were named so far in the discussion, but I suspect
there will be more.

> Do we want to give this class a separate name? Deprecated may feel a bit
> too strong in that context as it does imply eventual removal for many
> folks (including me, I guess). Is "superseded" better?

Traditional/established ways that will not go away?