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

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 2635 bytes --]

On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Over time, Git has grown quite a lot. With this evolution, many ideas
> > that were sensible at the time they were introduced are not anymore and
> > are thus considered to be deprecated. And while some deprecations may be
> > noted in manpages, most of them are actually deprecated in the "hive
> > mind" of the Git community, only.
> 
> There may be a new way that we hope is more suitable for folks who
> are learning Git today that achieves the same goal as an old way.
> It rarely means that the old way goes away, even when the new way is
> more capable than the old way and the use case the new way covers is
> a strict superset of the old way.
> 
> Such an introduction of a new way is *not* a breaking change.
> Everything the first paragraph talks about is a "deprecation" that
> does not break anything.  Documenting them is worthwhile, but it is
> worth pointing out that it not what the title of the topic "upcoming
> breaking changes" covers.
> 
> I think you should explicitly say that we deprecate but rarely
> remove and old ways are kept for backward compatibility in that
> introductory paragraph.  Then propose "But we may want to remove old
> ways and deliberately break at a large version bump every 5 years".
> That will lead your readers more smoothly to the next paragraph.

Agreed, I'll something along these lines.

> > Introduce a new document that lists upcoming breaking changes to address
> > this issue. This document serves multiple purposes:
> >
> >   - It is a way to facilitate discussion around proposed deprecations.
> >
> >   - It allows users to learn about deprecations and speak up in case
> >     they have good reasons why a certain feature should not be
> >     deprecated.
> >
> >   - It states intent and documents where the Git project wants to go.
> 
> 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)?

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?

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]