docs: introduce document to announce breaking changes
commit57ec9254eb996080c757708a7eec8d3657897222
authorPatrick Steinhardt <ps@pks.im>
Fri, 14 Jun 2024 06:42:34 +0000 (14 08:42 +0200)
committerJunio C Hamano <gitster@pobox.com>
Fri, 14 Jun 2024 16:08:52 +0000 (14 09:08 -0700)
treef38813ba492020fbe9c8b0e18e49c5b2db755f8e
parent786a3e4b8d754d2b14b1208b98eeb0a554ef19a8
docs: introduce document to announce breaking changes

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/BreakingChanges.txt [new file with mode: 0644]