Re: [PATCH v4 1/4] docs: introduce document to announce 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.
>
> Introduce a new document that tracks such breaking changes, but also
> deprecations which we are not willing to go through with, 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,
>     both in the case where we want to deprecate, but also in the case
>     where we don't want to deprecate a specific feature.
>
> 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.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++
>  1 file changed, 66 insertions(+)
>  create mode 100644 Documentation/BreakingChanges.md
>
> diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
> new file mode 100644
> index 0000000000..d8a26c9bf9
> --- /dev/null
> +++ b/Documentation/BreakingChanges.md
> @@ -0,0 +1,66 @@
> +# Upcoming breaking changes
> +
> +The Git project aims to ensure backwards compatibility to the best extent
> +possible. Minor releases will not break backwards compatibility unless there is
> +a very strong reason to do so, like for example a security vulnerability.
> +
> +Regardless of that, due to the age of the Git project, it is only natural to
> +accumulate a backlog of backwards-incompatible changes that will eventually be
> +required to keep the project aligned with a changing world. These changes fall
> +into several categories:
> +
> +  - Changes to long established defaults.
> +
> +  - Concepts that have been replaced with a superior design.
> +
> +  - Concepts, commands, configuration or options that have been lacking in major
> +    ways and that cannot be fixed.

The first two are easy to imagine.  If we change the default, people
may have to retrain their fingers or rewrite their scripts.  If
"log" that came later is so good that even those who were using
"whatchanged" have long switched to it, there will come time when
nobody even notices a removal of "whatchanged".

But the third one is puzzling.  If something falls into the "cannot
be fixed" category, is it still one of "These changes" that "will
eventually be required to [be made]"?

> +The Git project will thus irregularly release major versions that deliberately
> +break backwards compatibility with older versions. This is done to ensure that
> +Git remains relevant, safe and maintainable going forward. The release cadence
> +of major versions is typically measured in multiple years.

Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been
calling vX.Y.0 "feature releases" instead of calling them "major
versions", so the above use of the phrase "major version" can fit
in, but a more descriptive name, e.g., "breaking versions", might
convey the intention better, perhaps?

It may be more assuring to cite the last time such a breaking
version happened.  Was "Git 2.0" a breaking version?  If so, when
did it happen?  Were there other breaking versions in the past?

> +The intent of this document is to track upcoming deprecations for the next
> +major Git release. Furthermore, this document also tracks what will _not_ be
> +deprecated. This is done such that the outcome of discussions documente both
> +when the discussion favors deprecation, but also when it rejects a deprecation.

We seem to focus on removals and changes; will there be a case where
an upcoming addition is equally disrupting as removing an established
thing?  If we wanted to avoid focusing on deprecation/removals too
narrowly, we could tweak the wording below, with "deprecate a given
feature" -> "make the described change", etc.

> +Items should have a self-sufficient explanation why we want or do not want to
> +deprecate a given feature. If there are alternatives to the deprecated feature,
> +those alternatives should be pointed out to our users.
> ...

OK.

> +## Git 3.0
> +
> +The following subsections document upcoming breaking changes for Git 3.0. There
> +is no planned release date for this major version yet.

"upcoming breaking changes for" -> "breaking changes we plan to make in"?

> +Proposed changes and removals only include items which are "ready" to be done.
> +In other words, this is not supposed to be a wishlist of features that should
> +be changed to or replaced in case the alternative was implemented already.

OK.

> +### Changes
> +
> +### Removals
> +
> +## Superseded features that will not be deprecated
> +
> +Some features have gained newer replacements that aim to improve the design in
> +certain ways. The fact that there is a replacement does not automatically mean
> +that the old way of doing things will eventually be removed. This section tracks
> +those superseded features.

As the title says "superseded", to help non native speakers like me,
let's use a different and easier phrase with the same meaning in the
body text.  "... tracks those features with newer alternatives",
perhaps?

Thanks.