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

[Junio C Hamano <gitster@pobox.com>]

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.

> 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.

> The document is _not_ intended to cast every single discussion into
> stone. It is supposed to be a living document that may change over time
> when there are good reasons for it to change.

I'll stop here, as arguing how an individual bullet item is not
appropriate (i.e., deprecating it is a bad idea) should be left for
later stages of the discussion, after we accumulated more ideas.

Thanks.