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.
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.
--
2.45.1.410.g58bac47f8e.dirty
Attachment:
signature.asc
Description: PGP signature
