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