Hi,
this is another iteration of my patch series that intends to start
tracking upcoming breaking changes in Git.
Changes compared to v4:
- Converted the document to use AsciiDoc instead of MarkDown.
- Reword "major release" to "breaking release".
- Note Git 2.0, which is the last major breaking release.
- Note that minor bug fixes that lead to user visible changes in
behavior do not require a breaking release.
- Clarify that misdesigned features may be removed without
replacement, if necessary.
- Fix double negation in commit message of the last commit.
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkout
Documentation/BreakingChanges.txt | 115 ++++++++++++++++++++++++++++++
1 file changed, 115 insertions(+)
create mode 100644 Documentation/BreakingChanges.txt
Range-diff against v4:
1: 993b936348 ! 1: 67cb4de5cb docs: introduce document to announce breaking changes
@@ Commit message
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
- ## Documentation/BreakingChanges.md (new) ##
+ ## Documentation/BreakingChanges.txt (new) ##
@@
-+# Upcoming breaking changes
++= 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
@@ Documentation/BreakingChanges.md (new)
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
-+ - Changes to long established defaults.
++* 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 and which will thus be removed without any
++ replacement.
+
-+ - Concepts that have been replaced with a superior design.
++Explicitly not included in this list are fixes to minor bugs that may cause a
++change in user-visible behavior.
+
-+ - Concepts, commands, configuration or options that have been lacking in major
-+ ways and that cannot be fixed.
++The Git project irregularly releases breaking 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
++breaking versions is typically measured in multiple years. The last breaking
++releases were:
+
-+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.
++* Git 2.0, released in May 2014.
+
+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
@@ Documentation/BreakingChanges.md (new)
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+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,
++make the described change. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
@@ Documentation/BreakingChanges.md (new)
+revisited from time to time. So do not take items on this list to mean "it is
+settled, do not waste our time bringing it up again".
+
-+## Git 3.0
++== 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.
++is no planned release date for this breaking version yet.
+
+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.
+
-+### Changes
++=== Changes
+
-+### Removals
++=== Removals
+
-+## Superseded features that will not be deprecated
++== 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.
++those features with newer alternatives.
2: 7c84b2f957 ! 2: b36ffcbaa6 BreakingChanges: document upcoming change from "sha1" to "sha256"
@@ Commit message
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alternative was implemented already.
- ### Changes
+ === Changes
-+ - The default hash function for new repositories will be changed from "sha1"
-+ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-+ recommended against in FIPS 140-2 and similar certifications. Furthermore,
-+ there are practical attacks on SHA-1 that weaken its cryptographic properties:
++* The default hash function for new repositories will be changed from "sha1"
++ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
++ recommended against in FIPS 140-2 and similar certifications. Furthermore,
++ there are practical attacks on SHA-1 that weaken its cryptographic properties:
+++
++ ** The SHAppening (2015). The first demonstration of a practical attack
++ against SHA-1 with 2^57 operations.
++ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
++ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
++ attacks with 2^68 operations.
++ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
++ operations.
+++
++While we have protections in place against known attacks, it is expected
++that more attacks against SHA-1 will be found by future research. Paired
++with the ever-growing capability of hardware, it is only a matter of time
++before SHA-1 will be considered broken completely. We want to be prepared
++and will thus change the default hash algorithm to "sha256" for newly
++initialized repositories.
+++
++Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@xxxxxxxxxxx>,
++<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
++<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@xxxxxxxxxxxxxx>.
+
-+ - The SHAppening (2015). The first demonstration of a practical attack
-+ against SHA-1 with 2^57 operations.
-+
-+ - SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-+
-+ - Birthday-Near-Collision (2019). This attack allows for chosen prefix
-+ attacks with 2^68 operations.
-+
-+ - Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-+ operations.
-+
-+ While we have protections in place against known attacks, it is expected
-+ that more attacks against SHA-1 will be found by future research. Paired
-+ with the ever-growing capability of hardware, it is only a matter of time
-+ before SHA-1 will be considered broken completely. We want to be prepared
-+ and will thus change the default hash algorithm to "sha256" for newly
-+ initialized repositories.
-+
-+ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@xxxxxxxxxxx>,
-+ <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-+ <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@xxxxxxxxxxxxxx>.
-+
- ### Removals
+ === Removals
- ## Superseded features that will not be deprecated
+ == Superseded features that will not be deprecated
3: 91d78490c2 ! 3: 4142e472ac BreakingChanges: document removal of grafting
@@ Commit message
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@xxxxxxxxxxx>,
- ### Removals
+ === Removals
-+ - Support for grafting commits has long been superseded by git-replace(1).
-+ Grafts are inferior to replacement refs as the mechanism can lead to
-+ hard-to-diagnose problems when transferring objects between repositories.
-+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
-+ 2014-03-05) and will be removed.
++* Support for grafting commits has long been superseded by git-replace(1).
++ Grafts are inferior to replacement refs as the mechanism can lead to
++ hard-to-diagnose problems when transferring objects between repositories.
++ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
++ 2014-03-05) and will be removed.
+++
++Cf. <20140304174806.GA11561@xxxxxxxxxxxxxxxxxxxxx>.
+
-+ Cf. <20140304174806.GA11561@xxxxxxxxxxxxxxxxxxxxx>.
-+
- ## Superseded features that will not be deprecated
+ == Superseded features that will not be deprecated
Some features have gained newer replacements that aim to improve the design in
4: 40594bda5c ! 4: 9ff94b6f32 BreakingChanges: document that we do not plan to deprecate git-checkout
@@ Commit message
not the case though: the use of that command is still widespread, and it
is not expected that this will change anytime soon.
- Document that neither of these commands will not go away anytime soon.
+ Document that all three commands will remain for the foreseeable future.
This decision may be revisited in case we ever figure out that most
everyone has given up on any of the commands.
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: Some features have gained newer replacements that aim to improve the design in
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: 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.
+ those features with newer alternatives.
+
-+ - git-restore(1) and git-switch(1) have been introduced as a replacement for
-+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit
-+ of switching to git-restore(1) and git-switch(1) is contended, all three
-+ commands will stay.
-+
-+ This decision may get revisited in case we ever figure out that there are
-+ almost no users of any of the commands anymore.
-+
-+ Cf. <xmqqttjazwwa.fsf@gitster.g>,
-+ <xmqqleeubork.fsf@gitster.g>,
-+ <112b6568912a6de6672bf5592c3a718e@xxxxxxxxxxx>.
++* git-restore(1) and git-switch(1) have been introduced as a replacement for
++ git-checkout(1). As git-checkout(1) is quite established, and as the benefit
++ of switching to git-restore(1) and git-switch(1) is contended, all three
++ commands will stay.
+++
++This decision may get revisited in case we ever figure out that there are
++almost no users of any of the commands anymore.
+++
++Cf. <xmqqttjazwwa.fsf@gitster.g>,
++<xmqqleeubork.fsf@gitster.g>,
++<112b6568912a6de6672bf5592c3a718e@xxxxxxxxxxx>.
--
2.45.1.410.g58bac47f8e.dirty
Attachment:
signature.asc
Description: PGP signature
