1
+= Upcoming breaking changes
2
+
3
+The Git project aims to ensure backwards compatibility to the best extent
4
+possible. Minor releases will not break backwards compatibility unless there is
5
+a very strong reason to do so, like for example a security vulnerability.
6
+
7
+Regardless of that, due to the age of the Git project, it is only natural to
8
+accumulate a backlog of backwards-incompatible changes that will eventually be
9
+required to keep the project aligned with a changing world. These changes fall
10
+into several categories:
11
+
12
+* Changes to long established defaults.
13
+* Concepts that have been replaced with a superior design.
14
+* Concepts, commands, configuration or options that have been lacking in major
15
+ ways and that cannot be fixed and which will thus be removed without any
16
+ replacement.
17
+
18
+Explicitly not included in this list are fixes to minor bugs that may cause a
19
+change in user-visible behavior.
20
+
21
+The Git project irregularly releases breaking versions that deliberately break
22
+backwards compatibility with older versions. This is done to ensure that Git
23
+remains relevant, safe and maintainable going forward. The release cadence of
24
+breaking versions is typically measured in multiple years. We had the following
25
+major breaking releases in the past:
26
+
27
+* Git 1.6.0, released in August 2008.
28
+* Git 2.0, released in May 2014.
29
+
30
+We use <major>.<minor> release numbers these days, starting from Git 2.0. For
31
+future releases, our plan is to increment <major> in the release number when we
32
+make the next breaking release. Before Git 2.0, the release numbers were
33
+1.<major>.<minor> with the intention to increment <major> for "usual" breaking
34
+releases, reserving the jump to Git 2.0 for really large backward-compatibility
35
+breaking changes.
36
+
37
+The intent of this document is to track upcoming deprecations for future
38
+breaking releases. Furthermore, this document also tracks what will _not_ be
39
+deprecated. This is done such that the outcome of discussions document both
40
+when the discussion favors deprecation, but also when it rejects a deprecation.
41
+
42
+Items should have a clear summary of the reasons why we do or do not want to
43
+make the described change that can be easily understood without having to read
44
+the mailing list discussions. If there are alternatives to the changed feature,
45
+those alternatives should be pointed out to our users.
46
+
47
+All items should be accompanied by references to relevant mailing list threads
48
+where the deprecation was discussed. These references use message-IDs, which
49
+can visited via
50
+
51
+ https://lore.kernel.org/git/$message_id/
52
+
53
+to see the message and its surrounding discussion. Such a reference is there to
54
+make it easier for you to find how the project reached consensus on the
55
+described item back then.
56
+
57
+This is a living document as the environment surrounding the project changes
58
+over time. If circumstances change, an earlier decision to deprecate or change
59
+something may need to be revisited from time to time. So do not take items on
60
+this list to mean "it is settled, do not waste our time bringing it up again".
61
+
62
+== Git 3.0
63
+
64
+The following subsections document upcoming breaking changes for Git 3.0. There
65
+is no planned release date for this breaking version yet.
66
+
67
+Proposed changes and removals only include items which are "ready" to be done.
68
+In other words, this is not supposed to be a wishlist of features that should
69
+be changed to or replaced in case the alternative was implemented already.
70
+
71
+=== Changes
72
+
73
+=== Removals
74
+
75
+== Superseded features that will not be deprecated
76
+
77
+Some features have gained newer replacements that aim to improve the design in
78
+certain ways. The fact that there is a replacement does not automatically mean
79
+that the old way of doing things will eventually be removed. This section tracks
80
+those features with newer alternatives.