Skip to content

Commit 79efe2c

Browse files
gitstergitster
committed
Autogenerated HTML docs for v2.48.1-356-g03944
1 parent 253a665 commit 79efe2c

File tree

829 files changed

+128173
-26
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

829 files changed

+128173
-26
lines changed

‎BreakingChanges.adoc

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
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+
== Procedure
63+
64+
Discussing the desire to make breaking changes, declaring that breaking
65+
changes are made at a certain version boundary, and recording these
66+
decisions in this document, are necessary but not sufficient.
67+
Because such changes are expected to be numerous, and the design and
68+
implementation of them are expected to span over time, they have to
69+
be deployable trivially at such a version boundary.
70+
71+
The breaking changes MUST be guarded with the a compile-time switch,
72+
WITH_BREAKING_CHANGES, to help this process. When built with it,
73+
the resulting Git binary together with its documentation would
74+
behave as if these breaking changes slated for the next big version
75+
boundary are already in effect. We may also want to have a CI job
76+
or two to exercise the work-in-progress version of Git with these
77+
breaking changes.
78+
79+
80+
== Git 3.0
81+
82+
The following subsections document upcoming breaking changes for Git 3.0. There
83+
is no planned release date for this breaking version yet. The early
84+
adopter configuration used for changes for this release is `feature.git3`.
85+
86+
Proposed changes and removals only include items which are "ready" to be done.
87+
In other words, this is not supposed to be a wishlist of features that should
88+
be changed to or replaced in case the alternative was implemented already.
89+
90+
=== Changes
91+
92+
* The default hash function for new repositories will be changed from "sha1"
93+
to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
94+
recommended against in FIPS 140-2 and similar certifications. Furthermore,
95+
there are practical attacks on SHA-1 that weaken its cryptographic properties:
96+
+
97+
** The SHAppening (2015). The first demonstration of a practical attack
98+
against SHA-1 with 2^57 operations.
99+
** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
100+
** Birthday-Near-Collision (2019). This attack allows for chosen prefix
101+
attacks with 2^68 operations.
102+
** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
103+
operations.
104+
+
105+
While we have protections in place against known attacks, it is expected
106+
that more attacks against SHA-1 will be found by future research. Paired
107+
with the ever-growing capability of hardware, it is only a matter of time
108+
before SHA-1 will be considered broken completely. We want to be prepared
109+
and will thus change the default hash algorithm to "sha256" for newly
110+
initialized repositories.
111+
+
112+
An important requirement for this change is that the ecosystem is ready to
113+
support the "sha256" object format. This includes popular Git libraries,
114+
applications and forges.
115+
+
116+
There is no plan to deprecate the "sha1" object format at this point in time.
117+
+
118+
Cf. <[email protected]>,
119+
<[email protected]>,
120+
<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
121+
122+
=== Removals
123+
124+
* Support for grafting commits has long been superseded by git-replace(1).
125+
Grafts are inferior to replacement refs:
126+
+
127+
** Grafts are a local-only mechanism and cannot be shared across
128+
repositories.
129+
** Grafts can lead to hard-to-diagnose problems when transferring objects
130+
between repositories.
131+
+
132+
The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
133+
info/grafts as outdated, 2014-03-05) and will be removed.
134+
+
135+
Cf. <[email protected]>.
136+
137+
* The git-pack-redundant(1) command can be used to remove redundant pack files.
138+
The subcommand is unusably slow and the reason why nobody reports it as a
139+
performance bug is suspected to be the absence of users. We have nominated
140+
the command for removal and have started to emit a user-visible warning in
141+
c3b58472be (pack-redundant: gauge the usage before proposing its removal,
142+
2020-08-25) whenever the command is executed.
143+
+
144+
So far there was a single complaint about somebody still using the command, but
145+
that complaint did not cause us to reverse course. On the contrary, we have
146+
doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
147+
escalate deprecation warning to an error, 2023-03-23), the command dies unless
148+
the user passes the `--i-still-use-this` option.
149+
+
150+
There have not been any subsequent complaints, so this command will finally be
151+
removed.
152+
+
153+
Cf. <[email protected]>,
154+
<CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
155+
<[email protected]>,
156+
157+
* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
158+
and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
159+
the repository configuration.
160+
+
161+
The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
162+
short-hand notation for remote repositories., 2005-07-16) and was superseded by
163+
6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
164+
2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
165+
commit already mentions an upcoming deprecation of the ".git/branches/"
166+
directory, and starting with a1d4aa7424 (Add repository-layout document.,
167+
2005-09-01) we have also marked this layout as deprecated. Eventually we also
168+
started to migrate away from ".git/remotes/" in favor of config-based remotes,
169+
and we have marked the directory as legacy in 3d3d282146 (Documentation:
170+
Grammar correction, wording fixes and cleanup, 2011-08-23)
171+
+
172+
As our documentation mentions, these directories are not to be found in modern
173+
repositories at all and most users aren't even aware of these mechanisms. They
174+
have been deprecated for almost 20 years and 14 years respectively, and we are
175+
not aware of any active users that have complained about this deprecation.
176+
Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
177+
may cause confusion as "branches" are almost exclusively used in the context of
178+
references.
179+
+
180+
These features will be removed.
181+
182+
== Superseded features that will not be deprecated
183+
184+
Some features have gained newer replacements that aim to improve the design in
185+
certain ways. The fact that there is a replacement does not automatically mean
186+
that the old way of doing things will eventually be removed. This section tracks
187+
those features with newer alternatives.
188+
189+
* The features git-checkout(1) offers are covered by the pair of commands
190+
git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
191+
widespread, and it is not expected that this will change anytime soon, all
192+
three commands will stay.
193+
+
194+
This decision may get revisited in case we ever figure out that there are
195+
almost no users of any of the commands anymore.
196+
+
197+
Cf. <[email protected]>,
198+
<[email protected]>,
199+
<[email protected]>.

‎DecisionMaking.adoc

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
Decision-Making Process in the Git Project
2+
==========================================
3+
4+
Introduction
5+
------------
6+
This document describes the current decision-making process in the Git
7+
project. It is a descriptive rather than prescriptive doc; that is, we want to
8+
describe how things work in practice rather than explicitly recommending any
9+
particular process or changes to the current process.
10+
11+
Here we document how the project makes decisions for discussions
12+
(with or without patches), in scale larger than an individual patch
13+
series (which is fully covered by the SubmittingPatches document).
14+
15+
16+
Larger Discussions (with patches)
17+
---------------------------------
18+
As with discussions on an individual patch series, starting a larger-scale
19+
discussion often begins by sending a patch or series to the list. This might
20+
take the form of an initial design doc, with implementation following in later
21+
iterations of the series (for example,
22+
link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or
23+
link:https://lore.kernel.org/git/[email protected]/[config-based hooks]),
24+
or it might include a full implementation from the beginning.
25+
In either case, discussion progresses the same way for an individual patch series,
26+
until consensus is reached or the topic is dropped.
27+
28+
29+
Larger Discussions (without patches)
30+
------------------------------------
31+
Occasionally, larger discussions might occur without an associated patch series.
32+
These may be very large-scale technical decisions that are beyond the scope of
33+
even a single large patch series, or they may be more open-ended,
34+
policy-oriented discussions (examples:
35+
link:https://lore.kernel.org/git/[email protected]/[introducing Rust]
36+
or link:https://lore.kernel.org/git/[email protected]/[improving submodule UX]).
37+
In either case, discussion progresses as described above for general patch series.
38+
39+
For larger discussions without a patch series or other concrete implementation,
40+
it may be hard to judge when consensus has been reached, as there are not any
41+
official guidelines. If discussion stalls at this point, it may be helpful to
42+
restart discussion with an RFC patch series (such as a partial, unfinished
43+
implementation or proof of concept) that can be more easily debated.
44+
45+
When consensus is reached that it is a good idea, the original
46+
proposer is expected to coordinate the effort to make it happen,
47+
with help from others who were involved in the discussion, as
48+
needed.
49+
50+
For decisions that require code changes, it is often the case that the original
51+
proposer will follow up with a patch series, although it is also common for
52+
other interested parties to provide an implementation (or parts of the
53+
implementation, for very large changes).
54+
55+
For non-technical decisions such as community norms or processes, it is up to
56+
the community as a whole to implement and sustain agreed-upon changes.
57+
The project leadership committee (PLC) may help the implementation of
58+
policy decisions.
59+
60+
61+
Other Discussion Venues
62+
-----------------------
63+
Occasionally decision proposals are presented off-list, e.g. at the semi-regular
64+
Contributors' Summit. While higher-bandwidth face-to-face discussion is often
65+
useful for quickly reaching consensus among attendees, generally we expect to
66+
summarize the discussion in notes that can later be presented on-list. For an
67+
example, see the thread
68+
link:https://lore.kernel.org/git/[email protected]/[Notes
69+
from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.
70+
71+
We prefer that "official" discussion happens on the list so that the full
72+
community has opportunity to engage in discussion. This also means that the
73+
mailing list archives contain a more-or-less complete history of project
74+
discussions and decisions.

0 commit comments

Comments
 (0)