Re: [PATCH v6 0/4] docs: document upcoming breaking changes

> 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@zombino.com>,
>       +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
>       +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
> 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.