[v7,0/4] docs: document upcoming breaking changes

Message

Patrick Steinhardt June 14, 2024, 6:42 a.m. UTC

Hi,

this is another and hopefully the last version of this patch series that
starts to document upcoming breaking changes in Git.

Changes compared to v6:

  - Fix a typo in the third commit.

  - Document the version number schema and when we bump which part of
    our version, including historical 1.x days.

  - Drop the wrong remark that Git 1.6 should've been 2.0.

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 | 135 ++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 Documentation/BreakingChanges.txt

Range-diff against v6:
1:  a260bbf281 ! 1:  6348f27b59 docs: introduce document to announce breaking changes
    @@ Documentation/BreakingChanges.txt (new)
     +The Git project irregularly releases breaking versions that deliberately break
     +backwards compatibility with older versions. This is done to ensure that Git
     +remains relevant, safe and maintainable going forward. The release cadence of
    -+breaking versions is typically measured in multiple years. The last breaking
    -+releases were:
    ++breaking versions is typically measured in multiple years. We had the following
    ++major breaking releases in the past:
     +
    -+* Git 1.6, released in August 2008. In retrospect, this release should likely
    -+  have bumped the major version.
    ++* Git 1.6.0, released in August 2008.
     +* Git 2.0, released in May 2014.
     +
    ++We use <major>.<minor> release numbers these days, starting from Git 2.0. For
    ++future releases, our plan is to increment <major> in the release number when we
    ++make the next breaking release. Before Git 2.0, the release numbers were
    ++1.<major>.<minor> with the intention to increment <major> for "usual" breaking
    ++releases, reserving the jump to Git 2.0 for really large backward-compatibility
    ++breaking changes.
    ++
     +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
2:  f7c6a66f71 = 2:  d0ec38a25a BreakingChanges: document upcoming change from "sha1" to "sha256"
3:  b25b91a5e7 ! 3:  deee0bbf66 BreakingChanges: document removal of grafting
    @@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom
     +* Support for grafting commits has long been superseded by git-replace(1).
     +  Grafts are inferior to replacement refs:
     ++
    -+  ** Grafts are a local-only mechanism and cannot be shared across reositories.
    ++  ** Grafts are a local-only mechanism and cannot be shared across
    ++     repositories.
     +  ** Grafts can lead to hard-to-diagnose problems when transferring objects
     +     between repositories.
     ++
4:  4fafccc3b9 = 4:  25b20bb0ca BreakingChanges: document that we do not plan to deprecate git-checkout