| Message ID | a260bbf281d2975562a042a71ca0dd7f88f03da4.1717504292.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> writes: > +* Git 1.6, released in August 2008. In retrospect, this release should likely > + have bumped the major version. No need to reroll just for this alone, but back then, a non-zero third component did not mean they are maintenance releases (e.g., v1.5.3.3 was the third maintenance update for the v1.5.3 series) and v1.6.0 _was_ a departure, a breaking change from the v1.5.x series. It is more recent tradition that we only use three numbers. I'd strike the whole "In retrospect" comment if I were writing this. > +to see the message and its surrounding discussion. Such a reference is there to > +make it easier for you to find how the project reached concensus on the "concensus" -> "consensus".
On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > > > +* Git 1.6, released in August 2008. In retrospect, this release should likely > > + have bumped the major version. > > No need to reroll just for this alone, but back then, a non-zero > third component did not mean they are maintenance releases (e.g., > v1.5.3.3 was the third maintenance update for the v1.5.3 series) and > v1.6.0 _was_ a departure, a breaking change from the v1.5.x series. > > It is more recent tradition that we only use three numbers. I'd > strike the whole "In retrospect" comment if I were writing this. The reason why I included it is that I didn't want to create the impression that breaking releases may also happen when bumping the second version component. It did happen with v1.6.0, but in the future I think we'd want to always bump the first component on such releases, do we? Patrick
Patrick Steinhardt <ps@pks.im> writes: > On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote: >> Patrick Steinhardt <ps@pks.im> writes: >> >> > +* Git 1.6, released in August 2008. In retrospect, this release should likely >> > + have bumped the major version. >> >> No need to reroll just for this alone, but back then, a non-zero >> third component did not mean they are maintenance releases (e.g., >> v1.5.3.3 was the third maintenance update for the v1.5.3 series) and >> v1.6.0 _was_ a departure, a breaking change from the v1.5.x series. >> >> It is more recent tradition that we only use three numbers. I'd >> strike the whole "In retrospect" comment if I were writing this. > > The reason why I included it is that I didn't want to create the > impression that breaking releases may also happen when bumping the > second version component. It did happen with v1.6.0, but in the future I > think we'd want to always bump the first component on such releases, do > we? But "in retrospect we should have called it 2.0" is patently false; switching from 3-tuple version numbers to 2-tuple version numbers has nothing to do with introducing breaking changes. It needs to be rewritten in such a way that the readers would understand the following: Git 1.6.0, released in August 2008. These days, we use two-tuple numbers for feature releases (e.g. Git 2.45 and Git 2.45.0 with 0 as the third number are the same things) and maintenance releases have non-zero third number, so instead of going from Git 2.56 to Git 2.57, we would jump to Git 3.0 if we decide to make Git 2.56 the last feature release of the Git 2.0 series. With the versioning scheme used back then, going from Git 1.5.6 to Git 1.5.7 would have been equivalent move to Git 2.56 to Git 2.57, i.e. incremental and non-breaking feature release progression. Deciding to go from Git 1.5.6 to Git 1.6.0, instead of going to Git 1.5.7, was akin to moving to Git 3.0, signalling a breaking change, in today's versioning scheme. We were reserving the increment to the first digit for even larger breaking changes until Git 2.0 happened. Between Git 1.6.6 and Git 1.7.0, there were breaking changes. The same is true for the transtions between Git 1.7.12 and Git 1.8.0, between Git 1.4.4 and Git 1.5.0, and so on. They weren't as huge and controversial as the jump to Git 1.6.0, though.
Junio C Hamano <gitster@pobox.com> writes: > But "in retrospect we should have called it 2.0" is patently false; > switching from 3-tuple version numbers to 2-tuple version numbers > has nothing to do with introducing breaking changes. I tried to make it concise, and came up with the following on top of tweaked [v6 1/4] on 'seen'. Documentation/BreakingChanges.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git c/Documentation/BreakingChanges.txt w/Documentation/BreakingChanges.txt index d977915e52..9c2c5f2328 100644 --- c/Documentation/BreakingChanges.txt +++ w/Documentation/BreakingChanges.txt @@ -21,12 +21,19 @@ change in user-visible behavior. 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 major +breaking releases like these in the past: -* Git 1.6, released in August 2008. +* 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 feature 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
On Wed, Jun 05, 2024 at 10:52:10AM -0700, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > > > But "in retrospect we should have called it 2.0" is patently false; > > switching from 3-tuple version numbers to 2-tuple version numbers > > has nothing to do with introducing breaking changes. > > I tried to make it concise, and came up with the following on top of > tweaked [v6 1/4] on 'seen'. That is a good addition indeed and nicely explains what was going on back then, and how we handle it today. Thanks! Patrick
diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt new file mode 100644 index 0000000000..36327b13b8 --- /dev/null +++ b/Documentation/BreakingChanges.txt @@ -0,0 +1,74 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +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: + +* 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 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 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 +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +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 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +=== Removals + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives.
Over time, Git has grown quite a lot. With this evolution, many ideas that were sensible at the time they were introduced are not anymore and are thus considered to be deprecated. And while some deprecations may be noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only. Introduce a new document that tracks such breaking changes, but also deprecations which we are not willing to go through with, to address this issue. This document serves multiple purposes: - It is a way to facilitate discussion around proposed deprecations. - It allows users to learn about deprecations and speak up in case they have good reasons why a certain feature should not be deprecated. - It states intent and documents where the Git project wants to go, both in the case where we want to deprecate, but also in the case where we don't want to deprecate a specific feature. The document is _not_ intended to cast every single discussion into stone. It is supposed to be a living document that may change over time when there are good reasons for it to change. Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Documentation/BreakingChanges.txt | 74 +++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 Documentation/BreakingChanges.txt