[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.