From: Phillip Wood Date: Tue, 04 Jun 2024 14:23:09 GMT Subject: Re: [PATCH v6 0/4] docs: document upcoming breaking changes Message-ID: In-Reply-To: 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@zombino.com>, > +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, > +. > 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@sigill.intra.peff.net>. > + > 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.