Hi Patrick
On 04/06/2024 13:32, Patrick Steinhardt wrote:
Hi,
another day, another version of this patch series that aims to give a
framework for documenting upcoming breaking changes in Git.
Changes compared to v5:
- Note that Git 1.6 was a breaking release, despite the fact that its
major version wasn't bumped.
- Several smallish rewordings.
- Note that items on the lists should only be discussed anew when
circumstances have changed.
- Add some conditions to the move to "sha256". Also, note that we do
not plan to deprecate "sha1".
- Note that replacement refs are also superior over grafts because
they can be carried across repos.
This version looks good to me
Thanks for writing this document
Phillip
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 | 128 ++++++++++++++++++++++++++++++
1 file changed, 128 insertions(+)
create mode 100644 Documentation/BreakingChanges.txt
Range-diff against v5:
1: 67cb4de5cb ! 1: a260bbf281 docs: introduce document to announce breaking changes
@@ Documentation/BreakingChanges.txt (new)
+breaking versions is typically measured in multiple years. The last breaking
+releases were:
+
++* Git 1.6, released in August 2008. In retrospect, this release should likely
++ have bumped the major version.
+* 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
-+deprecated. This is done such that the outcome of discussions documente both
++The intent of this document is to track upcoming deprecations for future
++breaking releases. Furthermore, this document also tracks what will _not_ be
++deprecated. This is done such that the outcome of discussions document both
+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
-+make the described change. If there are alternatives to the changed feature,
++Items should have a clear summary of the reasons why we do or do not want to
++make the described change that can be easily understood without having to read
++the mailing list discussions. 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.txt (new)
+described item back then.
+
+This is a living document as the environment surrounding the project changes
-+over time. An earlier decision to deprecate or change something may need to be
-+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".
++over time. If circumstances change, an earlier decision to deprecate or change
++something may need to be 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
+
2: b36ffcbaa6 ! 2: f7c6a66f71 BreakingChanges: document upcoming change from "sha1" to "sha256"
@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alterna
+and will thus change the default hash algorithm to "sha256" for newly
+initialized repositories.
++
++An important requirement for this change is that the ecosystem is ready to
++support the "sha256" object format. This includes popular Git libraries,
++applications and forges.
+++
++There is no plan to deprecate the "sha1" object format at this point in time.
+++
+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@xxxxxxxxxxx>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@xxxxxxxxxxxxxx>.
3: 4142e472ac ! 3: b25b91a5e7 BreakingChanges: document removal of grafting
@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom
=== 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.
++ Grafts are inferior to replacement refs:
+++
++ ** Grafts are a local-only mechanism and cannot be shared across reositories.
++ ** Grafts can lead to hard-to-diagnose problems when transferring objects
++ between repositories.
+++
++The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
++info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <20140304174806.GA11561@xxxxxxxxxxxxxxxxxxxxx>.
+
4: 9ff94b6f32 ! 4: 4fafccc3b9 BreakingChanges: document that we do not plan to deprecate git-checkout
@@ Documentation/BreakingChanges.txt: Some features have gained newer replacements
that the old way of doing things will eventually be removed. This section tracks
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.
++* The features git-checkout(1) offers are covered by the pair of commands
++ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
++ widespread, and it is not expected that this will change anytime soon, 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.
