On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@xxxxxx> 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:
signature.asc
Description: PGP signature
