| Message ID | 993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> writes: > 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.md | 66 ++++++++++++++++++++++++++++++++ > 1 file changed, 66 insertions(+) > create mode 100644 Documentation/BreakingChanges.md > > diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md > new file mode 100644 > index 0000000000..d8a26c9bf9 > --- /dev/null > +++ b/Documentation/BreakingChanges.md > @@ -0,0 +1,66 @@ > +# 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. The first two are easy to imagine. If we change the default, people may have to retrain their fingers or rewrite their scripts. If "log" that came later is so good that even those who were using "whatchanged" have long switched to it, there will come time when nobody even notices a removal of "whatchanged". But the third one is puzzling. If something falls into the "cannot be fixed" category, is it still one of "These changes" that "will eventually be required to [be made]"? > +The Git project will thus irregularly release major 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 major versions is typically measured in multiple years. Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been calling vX.Y.0 "feature releases" instead of calling them "major versions", so the above use of the phrase "major version" can fit in, but a more descriptive name, e.g., "breaking versions", might convey the intention better, perhaps? It may be more assuring to cite the last time such a breaking version happened. Was "Git 2.0" a breaking version? If so, when did it happen? Were there other breaking versions in the past? > +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 > +when the discussion favors deprecation, but also when it rejects a deprecation. We seem to focus on removals and changes; will there be a case where an upcoming addition is equally disrupting as removing an established thing? If we wanted to avoid focusing on deprecation/removals too narrowly, we could tweak the wording below, with "deprecate a given feature" -> "make the described change", etc. > +Items should have a self-sufficient explanation why we want or do not want to > +deprecate a given feature. If there are alternatives to the deprecated feature, > +those alternatives should be pointed out to our users. > ... OK. > +## Git 3.0 > + > +The following subsections document upcoming breaking changes for Git 3.0. There > +is no planned release date for this major version yet. "upcoming breaking changes for" -> "breaking changes we plan to make in"? > +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. OK. > +### 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 superseded features. As the title says "superseded", to help non native speakers like me, let's use a different and easier phrase with the same meaning in the body text. "... tracks those features with newer alternatives", perhaps? Thanks.
On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: [snip] > > +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. > > The first two are easy to imagine. If we change the default, people > may have to retrain their fingers or rewrite their scripts. If > "log" that came later is so good that even those who were using > "whatchanged" have long switched to it, there will come time when > nobody even notices a removal of "whatchanged". > > But the third one is puzzling. If something falls into the "cannot > be fixed" category, is it still one of "These changes" that "will > eventually be required to [be made]"? Well, for a wider definition of "change", yes. In this case the change would be that the broken concept will be ripped out of Git without any replacement. I'll clarify this a bit further. > > +The Git project will thus irregularly release major 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 major versions is typically measured in multiple years. > > Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been > calling vX.Y.0 "feature releases" instead of calling them "major > versions", so the above use of the phrase "major version" can fit > in, but a more descriptive name, e.g., "breaking versions", might > convey the intention better, perhaps? I was trying to stick to the names that semantic versioning uses here, but I'm happy to adapt this accordingly. > It may be more assuring to cite the last time such a breaking > version happened. Was "Git 2.0" a breaking version? If so, when > did it happen? Were there other breaking versions in the past? I would definitely call Git 2.0 a breaking release as the changes to git-push(1)'s defaults were quite significant. Other than that I think lines are a bit blurry. We do minor breaking changes sometimes in case certain behaviour is deemed to be buggy, and fixing such buggy behaviour may at times result in user visible changes in behaviour. I wouldn't call that a breaking release though, because we certainly want to retain the ability to fix such bugs without bumping the major version every single time. Going down that path just means that the whole versioning schema becomes meaningless, like it has become for so many other projects nowadays. I'll also include a sentence along this line. > > +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 > > +when the discussion favors deprecation, but also when it rejects a deprecation. > > We seem to focus on removals and changes; will there be a case where > an upcoming addition is equally disrupting as removing an established > thing? If we wanted to avoid focusing on deprecation/removals too > narrowly, we could tweak the wording below, with "deprecate a given > feature" -> "make the described change", etc. Hard to predict, I guess. Let's just rephrase it to be a bit more generic. [snip] > > +### 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 superseded features. > > As the title says "superseded", to help non native speakers like me, > let's use a different and easier phrase with the same meaning in the > body text. "... tracks those features with newer alternatives", > perhaps? Sure, makes sense. Patrick
Patrick Steinhardt <ps@pks.im> writes: > I would definitely call Git 2.0 a breaking release as the changes to > git-push(1)'s defaults were quite significant. Git 1.6.0 was certainly a lot more controversial than the change in Git 2.0, as the end-users never expected Git will change even with ample pre-warning. We originally had all the "git-foo" in $PATH since 2005 when Git started, and we announced that we'll stop doing so in the release notes to Git 1.5.4 with instructions on how to adjust the scripts that use "git-foo" form. Even then end-users (back then they were a lot smaller population---we are talking about Aug 2008) complained quite loudly. [Readings] * https://git.github.io/htmldocs/RelNotes/1.5.4.txt * https://git.github.io/htmldocs/RelNotes/1.6.0.txt * https://lore.kernel.org/git/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/
On Mon, Jun 03, 2024 at 09:17:29AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > > > I would definitely call Git 2.0 a breaking release as the changes to > > git-push(1)'s defaults were quite significant. > > Git 1.6.0 was certainly a lot more controversial than the change in > Git 2.0, as the end-users never expected Git will change even with > ample pre-warning. We originally had all the "git-foo" in $PATH > since 2005 when Git started, and we announced that we'll stop doing > so in the release notes to Git 1.5.4 with instructions on how to > adjust the scripts that use "git-foo" form. Even then end-users > (back then they were a lot smaller population---we are talking about > Aug 2008) complained quite loudly. > > [Readings] > > * https://git.github.io/htmldocs/RelNotes/1.5.4.txt > * https://git.github.io/htmldocs/RelNotes/1.6.0.txt > * https://lore.kernel.org/git/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/ I had it in my mind that Git 1.6 was controversial, but I didn't quite know why exactly as I haven't been around at that point in time yet. I did read through its release notes to double check, but it seems like I missed the important part even though it was up front. Thanks for the history lesson, will add! Patrick
diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md new file mode 100644 index 0000000000..d8a26c9bf9 --- /dev/null +++ b/Documentation/BreakingChanges.md @@ -0,0 +1,66 @@ +# 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. + +The Git project will thus irregularly release major 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 major versions is typically measured in multiple years. + +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 +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 +deprecate a given feature. If there are alternatives to the deprecated 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. 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 major 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 superseded features.
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.md | 66 ++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/BreakingChanges.md