# [RFC PATCH] docs: document upcoming breaking changes 70 messages from 2024-05-07 to 2024-06-14. Participants: Patrick Steinhardt, Johannes Schindelin, Junio C Hamano, Phillip Wood, Dragan Simic, Justin Tobler, Karthik Nayak, Todd Zullinger. Thread: https://gitlist.dev/t/61428 ## Patrick Steinhardt, 2024-05-07 08:27 Subject: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps%40pks.im ``` 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 lists upcoming breaking changes 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. 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 --- Please note that this is explicitly marked as a request for comments. The proposed list of changes is neither exhaustive, nor do I necessarily think that every single item on that list is a good idea. The intent is to spark discussions, so some of the ideas on the list are controversial by design. Further note that this is not a "Git 3.0 is around the corner"-style document. I do not want to propose that a breaking Git 3.0 should be released soonish, and neither do I have the authority to decide that. I rather want us to document deprecations such that users, developers, hosters and distros are well aware of upcoming deprecations and can either speak up or prepare accordingly. Also, while a minority of the proposed deprecations does have links to mailing list threads, the majority doesn't. If we have good discussions to link to I'd love to add those links. I hope that some of the items will spark discussions that I can link to in v2. Patrick Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md new file mode 100644 index 0000000000..94d77a8af1 --- /dev/null +++ b/Documentation/UpcomingBreakingChanges.md @@ -0,0 +1,65 @@ +# Upcoming breaking changes + +The intent of this document is to track upcoming deprecations for the next major +Git release. It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. , + . + + - The default hash function for new repositories will be changed from "sha1" + to "sha256". + + - The default ref backend for new repositories will be changed from "files" to + "reftable". + +### Removals + + - git-config(1) has learned to use subcommands that replace implicit actions + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config + --unset-all`). The actions will be removed in favor of subcommands. + Prerequisite for this change is that the new subcommands have been out for at + least for two years to give script authors time to migrate. + + Cf. . + + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. + + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP + server like Apache. The protocol has not seen any updates recently and is + neither compatible with alternative hash functions nor with alternative ref + backends. It will thus be removed. + + - git-update-server-info(1) generates data required when serving data via the + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose + anymore and will be removed together with the protocol. This includes the + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the + `git repack -n` flag. + + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will + be removed in favor of git-blame(1). + + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. + + - git-filter-branch(1) can be used to rewrite history of a repository. It is + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has + been a source of multiple remote code execution vulnerabilities. The feature + will be removed in favor of `core.hooksDirectory` and the new config-based + hooks. -- 2.45.0 ``` ## Johannes Schindelin, 2024-05-07 10:38 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/e1350757-80d6-3ca6-3ef1-4b6ba496ba9e%40gmx.de In-Reply-To: ``` Hi Patrick, On Tue, 7 May 2024, Patrick Steinhardt wrote: > 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 lists upcoming breaking changes 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. I love it. FWIW my first reaction was: These deprecations should be mentioned in the release notes of the current versions, as a heads-up. But then I saw the impressive list you accumulated and agree that it needs to have its own document. > 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 > --- > > Please note that this is explicitly marked as a request for comments. > The proposed list of changes is neither exhaustive, nor do I necessarily > think that every single item on that list is a good idea. The intent is > to spark discussions, so some of the ideas on the list are controversial > by design. > > Further note that this is not a "Git 3.0 is around the corner"-style > document. I do not want to propose that a breaking Git 3.0 should be > released soonish, and neither do I have the authority to decide that. I > rather want us to document deprecations such that users, developers, > hosters and distros are well aware of upcoming deprecations and can > either speak up or prepare accordingly. > > Also, while a minority of the proposed deprecations does have links to > mailing list threads, the majority doesn't. If we have good discussions > to link to I'd love to add those links. I hope that some of the items > will spark discussions that I can link to in v2. > > Patrick > > Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++ > 1 file changed, 65 insertions(+) > create mode 100644 Documentation/UpcomingBreakingChanges.md > > diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md > new file mode 100644 > index 0000000000..94d77a8af1 > --- /dev/null > +++ b/Documentation/UpcomingBreakingChanges.md > @@ -0,0 +1,65 @@ > +# Upcoming breaking changes > + > +The intent of this document is to track upcoming deprecations for the next major > +Git release. It is supposed to be a living document where proposed changes and > +deprecations are up for discussion. > + > +## Git 3.0 > + > +### Changes > + > + - The default initial branch name will be changed from "master" to "main". > + > + Cf. , > + . > + > + - The default hash function for new repositories will be changed from "sha1" > + to "sha256". > + > + - The default ref backend for new repositories will be changed from "files" to > + "reftable". > + > +### Removals > + > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The actions will be removed in favor of subcommands. > + Prerequisite for this change is that the new subcommands have been out for at > + least for two years to give script authors time to migrate. > + > + Cf. . > + > + - git-http-push(1) can be used to push objects to a remote repository via > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > + nowadays anymore and will be removed together with the command. > + > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > + server like Apache. The protocol has not seen any updates recently and is > + neither compatible with alternative hash functions nor with alternative ref > + backends. It will thus be removed. > + > + - git-update-server-info(1) generates data required when serving data via the > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > + anymore and will be removed together with the protocol. This includes the > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > + `git repack -n` flag. > + > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > + concept has long been replaced by remotes and will thus be removed. > + > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will > + be removed in favor of git-blame(1). This is the only item I am not quite sure about. Its maintenance cost is negligible, I would think, and the cost of using a judging command name is less negligible. > + > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > + HTTP server. These scripts have been unmaintained for a significant amount of > + time and will be removed. > + > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > + very slow, hard to use and has many gotchas. It will thus be removed in favor > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > + > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has > + been a source of multiple remote code execution vulnerabilities. The feature > + will be removed in favor of `core.hooksDirectory` and the new config-based > + hooks. Since I already expressed interest in having this document, especially in the proposed form of being a _living_ document, i.e. subject to change, I would like to add: - The "dashed form", i.e. support for calling `git-` instead of `git ` in scripts, has been deprecated for a long time and the intention is still to remove it. - The command to import patches from Quilt seems to be used rarely, if ever, and will be removed. - Support for importing repositories from GNU Arch will be removed because it would not appear to have any users. - Support for interacting with CVS repositories (via `cvsimport`, `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by the number of times these commands have been mentioned recently. The code has been essentially unmaintained, too, and will be removed. Ciao, Johannes ``` ## Junio C Hamano, 2024-05-07 22:02 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqle4lnuvy.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt 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. There may be a new way that we hope is more suitable for folks who are learning Git today that achieves the same goal as an old way. It rarely means that the old way goes away, even when the new way is more capable than the old way and the use case the new way covers is a strict superset of the old way. Such an introduction of a new way is *not* a breaking change. Everything the first paragraph talks about is a "deprecation" that does not break anything. Documenting them is worthwhile, but it is worth pointing out that it not what the title of the topic "upcoming breaking changes" covers. I think you should explicitly say that we deprecate but rarely remove and old ways are kept for backward compatibility in that introductory paragraph. Then propose "But we may want to remove old ways and deliberately break at a large version bump every 5 years". That will lead your readers more smoothly to the next paragraph. > Introduce a new document that lists upcoming breaking changes 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. Another thing we may want to describe in such a document is what we do not want to drop and why, even when a new way that is a superset is available, which would give newbies with a natural "why don't we force everybody including the old timers to adopt new ways" question a reasonable answer. > 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. I'll stop here, as arguing how an individual bullet item is not appropriate (i.e., deprecating it is a bad idea) should be left for later stages of the discussion, after we accumulated more ideas. Thanks. ``` ## Phillip Wood, 2024-05-08 13:15 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: <077b69f1-cffa-44d5-8614-7f83b63442f8@gmail.com> URL: https://gitlist.dev/e/077b69f1-cffa-44d5-8614-7f83b63442f8%40gmail.com In-Reply-To: ``` Hi Patrick Thanks putting this together, I think it will be a useful way discussing deprecations and removals. On 07/05/2024 09:27, Patrick Steinhardt wrote: > 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 lists upcoming breaking changes 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. Is the plan to use this document to track the progress/status of proposed deprecations? For example the config based hooks implementation is stalled at the moment and would need some work before we can remove $GIT_DIR/hooks > +### Removals > + > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The actions will be removed in favor of subcommands. > + Prerequisite for this change is that the new subcommands have been out for at > + least for two years to give script authors time to migrate. I agree we want to allow plenty of time for script authors to migrate their scripts here. > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has > + been a source of multiple remote code execution vulnerabilities. I'm not sure about the reasoning here as a hook has to be enabled by the user before it is run. There are good reasons to prefer config based hooks such as the ability to run multiple scripts per hook event but I don't think they are inherently more secure. Best Wishes Phillip ``` ## Patrick Steinhardt, 2024-05-08 13:54 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZjuEMNsw-KARJjwx%40tanuki In-Reply-To: ``` On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote: > Patrick Steinhardt 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. > > There may be a new way that we hope is more suitable for folks who > are learning Git today that achieves the same goal as an old way. > It rarely means that the old way goes away, even when the new way is > more capable than the old way and the use case the new way covers is > a strict superset of the old way. > > Such an introduction of a new way is *not* a breaking change. > Everything the first paragraph talks about is a "deprecation" that > does not break anything. Documenting them is worthwhile, but it is > worth pointing out that it not what the title of the topic "upcoming > breaking changes" covers. > > I think you should explicitly say that we deprecate but rarely > remove and old ways are kept for backward compatibility in that > introductory paragraph. Then propose "But we may want to remove old > ways and deliberately break at a large version bump every 5 years". > That will lead your readers more smoothly to the next paragraph. Agreed, I'll something along these lines. > > Introduce a new document that lists upcoming breaking changes 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. > > Another thing we may want to describe in such a document is what we > do not want to drop and why, even when a new way that is a superset > is available, which would give newbies with a natural "why don't we > force everybody including the old timers to adopt new ways" question > a reasonable answer. Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)? Do we want to give this class a separate name? Deprecated may feel a bit too strong in that context as it does imply eventual removal for many folks (including me, I guess). Is "superseded" better? Patrick ``` ## Patrick Steinhardt, 2024-05-08 13:55 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZjuENtXjDZaX-0B0%40tanuki In-Reply-To: ``` On Tue, May 07, 2024 at 12:38:31PM +0200, Johannes Schindelin wrote: > Hi Patrick, > > On Tue, 7 May 2024, Patrick Steinhardt wrote: > > > 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 lists upcoming breaking changes 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. > > I love it. > > FWIW my first reaction was: These deprecations should be mentioned in the > release notes of the current versions, as a heads-up. But then I saw the > impressive list you accumulated and agree that it needs to have its own > document. Some of them are my own, some of them are Junio's. [snip] > > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will > > + be removed in favor of git-blame(1). > > This is the only item I am not quite sure about. Its maintenance cost is > negligible, I would think, and the cost of using a judging command name is > less negligible. There is of course still the problem of having multiple ways of doing the same thing, which does create mental overhead for users. But overall it's likely going to be negligible, both on our and on the user's side. So overall I don't mind this item much, and neither do I mind which of both commands we use. I do see the argument that git-annotate(1) is less judgemental though. > > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > > + HTTP server. These scripts have been unmaintained for a significant amount of > > + time and will be removed. > > + > > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > > + very slow, hard to use and has many gotchas. It will thus be removed in favor > > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > > + > > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has > > + been a source of multiple remote code execution vulnerabilities. The feature > > + will be removed in favor of `core.hooksDirectory` and the new config-based > > + hooks. > > Since I already expressed interest in having this document, especially in > the proposed form of being a _living_ document, i.e. subject to change, I > would like to add: > > - The "dashed form", i.e. support for calling `git-` instead of > `git ` in scripts, has been deprecated for a long time and the > intention is still to remove it. Agreed! > - The command to import patches from Quilt seems to be used rarely, if > ever, and will be removed. > > - Support for importing repositories from GNU Arch will be removed because > it would not appear to have any users. What even is GNU Arch...? Never heard of it before. > - Support for interacting with CVS repositories (via `cvsimport`, > `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by > the number of times these commands have been mentioned recently. The > code has been essentially unmaintained, too, and will be removed. Fair. I'd be happy to add these in v2 unless folks disagree. Patrick ``` ## Patrick Steinhardt, 2024-05-08 13:55 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZjuEPmSq3E28U6tJ%40tanuki In-Reply-To: <077b69f1-cffa-44d5-8614-7f83b63442f8@gmail.com> ``` On Wed, May 08, 2024 at 02:15:11PM +0100, Phillip Wood wrote: > Hi Patrick > > Thanks putting this together, I think it will be a useful way discussing > deprecations and removals. > > On 07/05/2024 09:27, Patrick Steinhardt wrote: > > 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 lists upcoming breaking changes 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. > > Is the plan to use this document to track the progress/status of proposed > deprecations? For example the config based hooks implementation is stalled > at the moment and would need some work before we can remove $GIT_DIR/hooks I also have it in my backlog to propose a file that may keep a record of long-running projects. The intent would be similar to this patch here, but it should also help newcomers to find projects to work on. This would track: - Large-scale efforts like the past SHA256 migration or removal of `the_repository`. - Small projects or microprojects like we have in GSoC to help out newcomers when they want to work on stuff. - Things we have already discussed, but simply didn't get landed yet like the hooks refactoring. So agreed, the hook refactorings should not be part of the deprecations document when it hasn't even landed yet. > > +### Removals > > + > > + - git-config(1) has learned to use subcommands that replace implicit actions > > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > > + --unset-all`). The actions will be removed in favor of subcommands. > > + Prerequisite for this change is that the new subcommands have been out for at > > + least for two years to give script authors time to migrate. > > I agree we want to allow plenty of time for script authors to migrate their > scripts here. > > > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has > > + been a source of multiple remote code execution vulnerabilities. > > I'm not sure about the reasoning here as a hook has to be enabled by the > user before it is run. There are good reasons to prefer config based hooks > such as the ability to run multiple scripts per hook event but I don't think > they are inherently more secure. I'll remove this item for now. We can discuss it again when (if) the config based mechanisms land. Patrick ``` ## Junio C Hamano, 2024-05-08 14:58 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqy18kxsdr.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: >> Another thing we may want to describe in such a document is what we >> do not want to drop and why, even when a new way that is a superset >> is available, which would give newbies with a natural "why don't we >> force everybody including the old timers to adopt new ways" question >> a reasonable answer. > > Okay, I see how that may make sense for some parts. I guess one of the > motivations here is things like git-checkout(1) and git-switch(1) / > git-restore(1)? Anything that we initially think it may make sense to remove but turns out that they are so ingrained in workflows that may lead some users to stick to pre-3.0 version. As this is a living document, instead of removing some ideas that are "voted down", recording the reason why we voted it down would make sense. Checkout and annotate are the ones that were named so far in the discussion, but I suspect there will be more. > Do we want to give this class a separate name? Deprecated may feel a bit > too strong in that context as it does imply eventual removal for many > folks (including me, I guess). Is "superseded" better? Traditional/established ways that will not go away? ``` ## Dragan Simic, 2024-05-08 15:59 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: <112b6568912a6de6672bf5592c3a718e@manjaro.org> URL: https://gitlist.dev/e/112b6568912a6de6672bf5592c3a718e%40manjaro.org In-Reply-To: ``` Hello Patrick, On 2024-05-08 15:54, Patrick Steinhardt wrote: > Okay, I see how that may make sense for some parts. I guess one of the > motivations here is things like git-checkout(1) and git-switch(1) / > git-restore(1)? As I wrote already, [1] I really see no reasons why git-switch(1) or git-restore(1) should be deprecated. That would make zero sense to me. [1] https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/ ``` ## Justin Tobler, 2024-05-10 02:15 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/obsrinbe2uvemiq7q22zrbcln2lmfaukn6lqn7nagrassoicb4%40ihwb6ifpjomc In-Reply-To: ``` On 24/05/07 10:27AM, Patrick Steinhardt wrote: +### Removals > + > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The actions will be removed in favor of subcommands. > + Prerequisite for this change is that the new subcommands have been out for at > + least for two years to give script authors time to migrate. > + > + Cf. . > + > + - git-http-push(1) can be used to push objects to a remote repository via > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > + nowadays anymore and will be removed together with the command. > + > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > + server like Apache. The protocol has not seen any updates recently and is > + neither compatible with alternative hash functions nor with alternative ref > + backends. It will thus be removed. > + > + - git-update-server-info(1) generates data required when serving data via the > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > + anymore and will be removed together with the protocol. This includes the > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > + `git repack -n` flag. > + > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > + concept has long been replaced by remotes and will thus be removed. > + > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will > + be removed in favor of git-blame(1). > + > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > + HTTP server. These scripts have been unmaintained for a significant amount of > + time and will be removed. > + > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > + very slow, hard to use and has many gotchas. It will thus be removed in favor > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > + > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has > + been a source of multiple remote code execution vulnerabilities. The feature > + will be removed in favor of `core.hooksDirectory` and the new config-based > + hooks. I would like to see the double dot and triple dot syntax (".." and "...") removed from `git-diff(1)` as I think they get easily confused with revision ranges. -Justin ``` ## Junio C Hamano, 2024-05-10 04:47 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqq1q6aqnm2.fsf%40gitster.g In-Reply-To: ``` Justin Tobler writes: > I would like to see the double dot and triple dot syntax (".." and "...") > removed from `git-diff(1)` as I think they get easily confused with > revision ranges. I tend to agree that the double-dot notation does not need to exist as it can be done with a pair of bog-standard revs. But triple-dot notation needs a replacement syntax that is just as easy to access the feature as the current syntax. After updating a tip of a topic branch, $ git diff topic@{1}...topic is extremely useful (in addition to "git log -p" and the like, of course, with the same range). Also during a conflicted merge $ git diff ...MERGE_BASE and its reverse are very handy. Having to say "--merge-base" is probably a usability regression. If somebody wants to pursue this further, my recommendation is to treat the two separately. * Deprecate and eventually remove double-dot notation. - First, notice the use of double-dot notation. builtin/diff.c:symdiff_prepare() is the place to do so. Issue a warning about deprecation and possibility of an eventual removal, and tell the users to use "diff A B" instead of "diff A..B". - Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0. - Remove the support for A..B. * Deprecate and eventually remove triple-dot notation. - Introduce a new syntax to allow an access to the "symmetric diff" feature just as easily as the current syntax. Wait for a handful releases to gauge its acceptance by the end users. - Then notice the use of triple-dot notation. The place to do sois the same builtin/diff.c:symdiff_prepare(). Give a warning about deprecation and possibility of an eventual removal, and tell the users to use that new syntax we introduced. - Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0. - Remove the support for A...B. ``` ## Patrick Steinhardt, 2024-05-10 11:36 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/Zj4Gx6LGSoTGc3eW%40tanuki In-Reply-To: <112b6568912a6de6672bf5592c3a718e@manjaro.org> ``` On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote: > Hello Patrick, > > On 2024-05-08 15:54, Patrick Steinhardt wrote: > > Okay, I see how that may make sense for some parts. I guess one of the > > motivations here is things like git-checkout(1) and git-switch(1) / > > git-restore(1)? > > As I wrote already, [1] I really see no reasons why git-switch(1) or > git-restore(1) should be deprecated. That would make zero sense to me. > > [1] > https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/ Note that the discussion here is the other way round: whether we want to eventually deprecate tools like git-checkout(1) that have newer replacements. Junio argues that there being a replacement is not by itself a good enough reason to eventually remove the old one, which I'm fine with. Patrick ``` ## Dragan Simic, 2024-05-10 12:43 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/bcaa054e4081a43bef349a1079895374%40manjaro.org In-Reply-To: ``` Hello Patrick, On 2024-05-10 13:36, Patrick Steinhardt wrote: > On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote: >> On 2024-05-08 15:54, Patrick Steinhardt wrote: >> > Okay, I see how that may make sense for some parts. I guess one of the >> > motivations here is things like git-checkout(1) and git-switch(1) / >> > git-restore(1)? >> >> As I wrote already, [1] I really see no reasons why git-switch(1) or >> git-restore(1) should be deprecated. That would make zero sense to >> me. >> >> [1] >> https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/ > > Note that the discussion here is the other way round: whether we want > to > eventually deprecate tools like git-checkout(1) that have newer > replacements. Junio argues that there being a replacement is not by > itself a good enough reason to eventually remove the old one, which I'm > fine with. I agree that not deprecating git-checkout(1) and similar utilities is the way to go. It's rather safe to assume that many users still use them, despite the existence of the newer replacements. Also, not just users, but various scripts. ``` ## Patrick Steinhardt, 2024-05-14 06:16 Subject: [RFC PATCH v2] docs: document upcoming breaking changes Message-ID: <2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im> URL: https://gitlist.dev/e/2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps%40pks.im In-Reply-To: ``` 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 lists upcoming 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 --- I have tried to accommodate for all feedback to v1. Most notably: - I have introduced a new section that documents concepts that are _not_ to be deprecated. The intent is to capture discussions around proposed deprecations where we ultimately decide that we do not (yet) want to deprecate it. - I have added some more proposed deprecations. As before, all of this is up for discussion and I do not want to force any of the proposed deprecations onto anybody. - I have dropped the "$GITDIR/hooks" deprecation item for now. It is premature to have it at this point in time given that the config-based approach isn't even close to landing. Patrick Range-diff against v1: 1: a78d68ecc2 ! 1: 2ef53ff98b docs: document upcoming breaking changes @@ Commit message noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only. - Introduce a new document that lists upcoming breaking changes to address + Introduce a new document that lists upcoming 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. @@ Commit message they have good reasons why a certain feature should not be deprecated. - - It states intent and documents where the Git project wants to go. + - 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 @@ Documentation/UpcomingBreakingChanges.md (new) @@ +# 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. It is supposed to be a living document where proposed changes and ++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. ++ ++It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 @@ Documentation/UpcomingBreakingChanges.md (new) + +### Removals + -+ - git-config(1) has learned to use subcommands that replace implicit actions -+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config -+ --unset-all`). The actions will be removed in favor of subcommands. -+ Prerequisite for this change is that the new subcommands have been out for at -+ least for two years to give script authors time to migrate. -+ -+ Cf. . -+ + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. @@ Documentation/UpcomingBreakingChanges.md (new) + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + -+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will -+ be removed in favor of git-blame(1). -+ + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. @@ Documentation/UpcomingBreakingChanges.md (new) + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + -+ - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has -+ been a source of multiple remote code execution vulnerabilities. The feature -+ will be removed in favor of `core.hooksDirectory` and the new config-based -+ hooks. ++ - The "dashed form", i.e. support for calling `git-` instead of ++ `git ` in scripts, has been deprecated for a long time and will be ++ removed. ++ ++ - The command to import patches from Quilt seems to be used rarely, if ++ ever, and will be removed. ++ ++ - Support for importing repositories from GNU Arch will be removed because ++ it would not appear to have any users. ++ ++ - Support for interacting with CVS repositories (via `cvsimport`, ++ `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by ++ the number of times these commands have been mentioned recently. The ++ code has been essentially unmaintained, too, and will be removed. ++ ++ - 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. ++ ++## 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. ++ ++ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As ++ the maintenance burden of carrying both of these commands is negligible, both ++ commands will stay. ++ ++ - 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. ++ ++ - git-config(1) has learned to use subcommands that replace implicit actions ++ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config ++ --unset-all`). The action flags will not be removed in the next major Git ++ release as there likely exist a lot of scripts out there that use the old ++ syntax. ++ ++ Cf. . Documentation/UpcomingBreakingChanges.md | 119 +++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md new file mode 100644 index 0000000000..8c7a5f2f38 --- /dev/null +++ b/Documentation/UpcomingBreakingChanges.md @@ -0,0 +1,119 @@ +# 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. + +It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. , + . + + - The default hash function for new repositories will be changed from "sha1" + to "sha256". + + - The default ref backend for new repositories will be changed from "files" to + "reftable". + +### Removals + + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. + + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP + server like Apache. The protocol has not seen any updates recently and is + neither compatible with alternative hash functions nor with alternative ref + backends. It will thus be removed. + + - git-update-server-info(1) generates data required when serving data via the + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose + anymore and will be removed together with the protocol. This includes the + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the + `git repack -n` flag. + + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. + + - git-filter-branch(1) can be used to rewrite history of a repository. It is + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + + - The "dashed form", i.e. support for calling `git-` instead of + `git ` in scripts, has been deprecated for a long time and will be + removed. + + - The command to import patches from Quilt seems to be used rarely, if + ever, and will be removed. + + - Support for importing repositories from GNU Arch will be removed because + it would not appear to have any users. + + - Support for interacting with CVS repositories (via `cvsimport`, + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by + the number of times these commands have been mentioned recently. The + code has been essentially unmaintained, too, and will be removed. + + - 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. + +## 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. + + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As + the maintenance burden of carrying both of these commands is negligible, both + commands will stay. + + - 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. + + - git-config(1) has learned to use subcommands that replace implicit actions + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config + --unset-all`). The action flags will not be removed in the next major Git + release as there likely exist a lot of scripts out there that use the old + syntax. + + Cf. . -- 2.45.GIT ``` ## Patrick Steinhardt, 2024-05-14 06:50 Subject: Re: [RFC PATCH] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZkMJxxKdr2hd1mzR%40tanuki In-Reply-To: ``` On Thu, May 09, 2024 at 09:47:49PM -0700, Junio C Hamano wrote: > Justin Tobler writes: > > > I would like to see the double dot and triple dot syntax (".." and "...") > > removed from `git-diff(1)` as I think they get easily confused with > > revision ranges. > > I tend to agree that the double-dot notation does not need to exist > as it can be done with a pair of bog-standard revs. But triple-dot > notation needs a replacement syntax that is just as easy to access > the feature as the current syntax. After updating a tip of a topic > branch, > > $ git diff topic@{1}...topic > > is extremely useful (in addition to "git log -p" and the like, of > course, with the same range). Also during a conflicted merge > > $ git diff ...MERGE_BASE > > and its reverse are very handy. Having to say "--merge-base" is > probably a usability regression. > > If somebody wants to pursue this further, my recommendation is to > treat the two separately. > > * Deprecate and eventually remove double-dot notation. > > - First, notice the use of double-dot notation. > builtin/diff.c:symdiff_prepare() is the place to do so. Issue > a warning about deprecation and possibility of an eventual > removal, and tell the users to use "diff A B" instead of "diff > A..B". > > - Gain consensus that the removal is a good idea. Finish these > steps long before Git 3.0. > > - Remove the support for A..B. > > * Deprecate and eventually remove triple-dot notation. > > - Introduce a new syntax to allow an access to the "symmetric > diff" feature just as easily as the current syntax. Wait for > a handful releases to gauge its acceptance by the end users. > > - Then notice the use of triple-dot notation. The place to do > sois the same builtin/diff.c:symdiff_prepare(). Give a warning > about deprecation and possibility of an eventual removal, and > tell the users to use that new syntax we introduced. > > - Gain consensus that the removal is a good idea. Finish these > steps long before Git 3.0. > > - Remove the support for A...B. I'll leave these for a future iteration for now given that there is more work that needs to be done in this context. Patrick ``` ## Karthik Nayak, 2024-05-14 10:48 Subject: Re: [RFC PATCH v2] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/CAOLa%3DZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv%2BpVu1Nyw%40mail.gmail.com In-Reply-To: <2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im> ``` Patrick Steinhardt writes: [snip] > +### Removals > + > + - git-http-push(1) can be used to push objects to a remote repository via > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > + nowadays anymore and will be removed together with the command. > + > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > + server like Apache. The protocol has not seen any updates recently and is > + neither compatible with alternative hash functions nor with alternative ref > + backends. It will thus be removed. > + > + - git-update-server-info(1) generates data required when serving data via the > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > + anymore and will be removed together with the protocol. This includes the > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > + `git repack -n` flag. > + > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > + concept has long been replaced by remotes and will thus be removed. > + > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > + HTTP server. These scripts have been unmaintained for a significant amount of > + time and will be removed. > + > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > + very slow, hard to use and has many gotchas. It will thus be removed in favor > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > + > + - The "dashed form", i.e. support for calling `git-` instead of > + `git ` in scripts, has been deprecated for a long time and will be > + removed. > + > + - The command to import patches from Quilt seems to be used rarely, if > + ever, and will be removed. > + > + - Support for importing repositories from GNU Arch will be removed because > + it would not appear to have any users. > + > + - Support for interacting with CVS repositories (via `cvsimport`, > + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by > + the number of times these commands have been mentioned recently. The > + code has been essentially unmaintained, too, and will be removed. > + > + - 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. I think it is worthwhile also looking at the number of commands we have and see that some of these could possibly be marked deprecated, maybe removal could follow too: * add, stage Here, `stage` is synonym and can be just dropped. * prune, prune-packed `prune-packed` prunes objects from packed files, perhaps could be a sub-command on the existing `prune` command. * annotate, blame, pickaxe You've mentioned `annotate` below, but we could also remove `pickaxe`. * log, whatchanged, shortlog Here `log` already handles what the other two commands do. * for-each-ref, show-ref These two commands do very similar things, i.e. list references. Both diverge in the features they provided, but its not clear why we have the two. * verify-commit, verify-pack, verify-tag These could probably be subcommands under the verify command. * diff, diff-files, diff-index, diff-tree Here, `diff` seems to handle everything that the others do. > +## 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. > + > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As > + the maintenance burden of carrying both of these commands is negligible, both > + commands will stay. > + > While maintenance burden is an issue for us. There is also an user experience point of view, having similar commands doing similar operations is often a cause for confusion. > + - 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. > + > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The action flags will not be removed in the next major Git > + release as there likely exist a lot of scripts out there that use the old > + syntax. ``` ## Patrick Steinhardt, 2024-05-14 11:22 Subject: Re: [RFC PATCH v2] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZkNJaaKTTKbns8wo%40tanuki In-Reply-To: ``` On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote: > Patrick Steinhardt writes: [snip] > I think it is worthwhile also looking at the number of commands we have > and see that some of these could possibly be marked deprecated, maybe > removal could follow too: > > * add, stage > Here, `stage` is synonym and can be just dropped. I wonder whether there are any arguments in favor of git-stage(1). I myself haven't even been aware of this command and have never seen it out there in the wild. Which would be an indicator that we can safely remove it. Comments? > * prune, prune-packed > `prune-packed` prunes objects from packed files, perhaps could be a > sub-command on the existing `prune` command. I think we should refrain from adding anything to this document that is not yet feasible. In other words, once git-prune(1) learns to prune packed objects we may want to think about whether git-prune-packed(1) can be deprecated, but not beforehand. > * annotate, blame, pickaxe > You've mentioned `annotate` below, but we could also remove `pickaxe`. I think most oldtimers use git-blame(1), whereas git-annotate(1) has been introduced to make the command less judgemental. I'd thus say that this falls into the category of commands that we wouldn't want to deprecate because they are both used. For git-pickaxe(1) it's a bit of a different story though. We do not even have a manpage for it anymore. I wouldn't mind deprecating that one fully. > * log, whatchanged, shortlog > Here `log` already handles what the other two commands do. Does git-log(1) really support everything that git-shortlog(1) does? If so then this would be entirely new to me, but you never know with Git :) git-whatchanged(1) has been essentially deprecated already. So that may be a worthwhile addition. > * for-each-ref, show-ref > These two commands do very similar things, i.e. list references. Both > diverge in the features they provided, but its not clear why we have the > two. True, they have clear overlap and both are part of plumbing. I never quite know which one to pick. But git-show-ref(1) handles things that git-for-each-ref(1) doesn't ("--exists", "--verify") and the other way round ("--stdin", "--sort=", many more). Honestly, I think that both of these are not ideal. I think we should think bigger in this context and introduce a new command with proper subcommands to make the whole story around refs more coherent and discoverable: # Replaces git-show-ref(1) and git-for-each-ref(1). $ git refs list # Replaces `git show-ref --exists`. $ git refs exist # Replaces `git show-ref --verify `. $ git refs show # Replaces git-symbolic-ref(1) to show a ref. $ git refs resolve # Replaces git-pack-ref(1). $ git refs pack # Replaces git-update-ref(1). $ git refs write # Replaces git-check-ref-format(1). $ git refs check-format This is of course a much larger topic and something that is very much up for discussion. But in any case, it indicates that a deprecation would be premature at this point in time. > * verify-commit, verify-pack, verify-tag > These could probably be subcommands under the verify command. Same here -- as we don't have the command yet, I think it's premature the old commands to a list of deprecations. > * diff, diff-files, diff-index, diff-tree > Here, `diff` seems to handle everything that the others do. These do have different scopes though. While git-diff(1) is part of porcelain, the others are all part of the plumbing layer. As such, we provide different guarantees. In practice it's likely a different story though as my assumption is that git-diff(1) will be used in scripts a lot. But in any case, I think that this is a separate topic that would first need some discussion. > > +## 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. > > + > > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As > > + the maintenance burden of carrying both of these commands is negligible, both > > + commands will stay. > > + > > > > While maintenance burden is an issue for us. There is also an user > experience point of view, having similar commands doing similar > operations is often a cause for confusion. In this case I think it's okay as the documentation of git-annotate(1) clearly states that it is the same as git-blame(1). But it is certainly true that synonyms also add to perceived complexity of Git. Patrick ``` ## Dragan Simic, 2024-05-14 12:32 Subject: Re: [RFC PATCH v2] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/f7dbf46360104fe9110526acf19be755%40manjaro.org In-Reply-To: ``` Hello Karthik, On 2024-05-14 12:48, Karthik Nayak wrote: > I think it is worthwhile also looking at the number of commands we have > and see that some of these could possibly be marked deprecated, maybe > removal could follow too: > > * log, whatchanged, shortlog > Here `log` already handles what the other two commands do. I haven't used "git shortlog" myself, but I think it sees a fair amount of use in various project maintainer reports. Thus, I don't think it should be marked as deprecated. ``` ## Junio C Hamano, 2024-05-14 15:45 Subject: Re: [RFC PATCH v2] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqh6f05rdd.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: >> * annotate, blame, pickaxe >> You've mentioned `annotate` below, but we could also remove `pickaxe`. > > I think most oldtimers use git-blame(1), whereas git-annotate(1) has > been introduced to make the command less judgemental. I'd thus say that > this falls into the category of commands that we wouldn't want to > deprecate because they are both used. Personally I do not think blame is "judgemental" in the first place, and I do not think being "judgemental" is bad to begin with. "git annotate" was there first as a Perl script, added by c65e8987 (Add git-annotate, a tool for assigning blame., 2006-02-20). It is intersting to note that "annotate" was advertised as a tool for assigning blame. "git blame" was written almost around the same time but with "-c" compatiblity mode to mimick "git annotate", added by cbfb73d7 (Add git-blame, a tool for assigning blame., 2006-02-21). A healthy competition between "annotate" and "blame" continued until f789e347 (Remove git-annotate.perl and create a builtin-alias for git-blame, 2006-10-09) retired the "git annotate" Perl script, and replaced it with an invocation of "git blame -c". "git blame" was rewritten under the codename "git pickaxe" (cf. https://lore.kernel.org/git/7vr6xddm7h.fsf@assigned-by-dhcp.cox.net/), and was released at cee7f245 (git-pickaxe: blame rewritten., 2006-10-19). acca687f (git-pickaxe: retire pickaxe, 2006-11-08) made it take over the old implementation of "git blame". The name "pickaxe" can be easily removed, as the log message of acca687f already said back then. As everybody noticed, it is not even documented. >> * log, whatchanged, shortlog >> Here `log` already handles what the other two commands do. > > Does git-log(1) really support everything that git-shortlog(1) does? Of course not. The filtering behaviour of shortlog is unique to the command. > This is of course a much larger topic and something that is very much up > for discussion. But in any case, it indicates that a deprecation would > be premature at this point in time. Yes, please exclude anything that needs new development while discussing this topic. Anybody jumping into this discussion should take the word "upcoming" in the title more seriously. So I won't talk about unifying "describe" and "name-rev" somehow ;-) >> * verify-commit, verify-pack, verify-tag >> These could probably be subcommands under the verify command. > > Same here -- as we don't have the command yet, I think it's premature > the old commands to a list of deprecations. > >> * diff, diff-files, diff-index, diff-tree >> Here, `diff` seems to handle everything that the others do. No, diff-files, diff-index and diff-tree can do their thing without getting broken by end-user configuration. Writing your script with "git diff" and you can keep both halves. ``` ## Patrick Steinhardt, 2024-05-24 12:54 Subject: [PATCH v3] docs: document upcoming breaking changes Message-ID: <84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im> URL: https://gitlist.dev/e/84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps%40pks.im In-Reply-To: ``` 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 lists upcoming 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 --- I've dropped the RFC prefix of this series now. I think that the overall idea has been received well, and folks are supportive of documenting upcoming breaking changes. There's only a single change compared to the second version. In any case, most of the proposed deprecations didn't get much pushback. I'm less sure whether this is because people didn't look, or because they silently agree with what I propose for deprecation. I'm going to assume it's the latter. If you feel otherwise, my proposed way forward would be to drop most of the items, merge the document, and then add items via separate threads where we can discuss each deprecation on its own. Please let me know your preference! Patrick Range-diff against v2: 1: 8e268a291b ! 1: 84c01f1b0a docs: document upcoming breaking changes @@ Documentation/UpcomingBreakingChanges.md (new) + They have been outdated since e650d0643b (docs: mark info/grafts as outdated, + 2014-03-05) and will be removed. + ++ - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9 ++ (git-pickaxe: retire pickaxe, 2006-11-08) and will be removed. ++ +## Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md new file mode 100644 index 0000000000..d057ef7cb3 --- /dev/null +++ b/Documentation/UpcomingBreakingChanges.md @@ -0,0 +1,122 @@ +# 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. + +It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. , + . + + - The default hash function for new repositories will be changed from "sha1" + to "sha256". + + - The default ref backend for new repositories will be changed from "files" to + "reftable". + +### Removals + + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. + + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP + server like Apache. The protocol has not seen any updates recently and is + neither compatible with alternative hash functions nor with alternative ref + backends. It will thus be removed. + + - git-update-server-info(1) generates data required when serving data via the + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose + anymore and will be removed together with the protocol. This includes the + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the + `git repack -n` flag. + + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. + + - git-filter-branch(1) can be used to rewrite history of a repository. It is + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + + - The "dashed form", i.e. support for calling `git-` instead of + `git ` in scripts, has been deprecated for a long time and will be + removed. + + - The command to import patches from Quilt seems to be used rarely, if + ever, and will be removed. + + - Support for importing repositories from GNU Arch will be removed because + it would not appear to have any users. + + - Support for interacting with CVS repositories (via `cvsimport`, + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by + the number of times these commands have been mentioned recently. The + code has been essentially unmaintained, too, and will be removed. + + - 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. + + - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9 + (git-pickaxe: retire pickaxe, 2006-11-08) and will be removed. + +## 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. + + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As + the maintenance burden of carrying both of these commands is negligible, both + commands will stay. + + - 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. + + - git-config(1) has learned to use subcommands that replace implicit actions + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config + --unset-all`). The action flags will not be removed in the next major Git + release as there likely exist a lot of scripts out there that use the old + syntax. + + Cf. . base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f -- 2.45.1.246.gb9cfe4845c.dirty ``` ## Junio C Hamano, 2024-05-24 17:27 Subject: Re: [PATCH v3] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqsey7ktn2.fsf%40gitster.g In-Reply-To: <84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im> ``` Patrick Steinhardt writes: > case, most of the proposed deprecations didn't get much pushback. I'm > less sure whether this is because people didn't look, or because they > silently agree with what I propose for deprecation. Or because I explicitly said that first we'll brainstorm, in order to encourage generation of more ideas, without shooting other people's ideas down? > Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++ > 1 file changed, 122 insertions(+) > create mode 100644 Documentation/UpcomingBreakingChanges.md > > diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md > new file mode 100644 > index 0000000000..d057ef7cb3 > --- /dev/null > +++ b/Documentation/UpcomingBreakingChanges.md > @@ -0,0 +1,122 @@ > +# 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. > + > +It is supposed to be a living document where proposed changes and > +deprecations are up for discussion. OK. > +## Git 3.0 Question. Will we have "## Git 4.0" etc., to indicate the timelines (some stuff we might eventually replace/change, but we may not ready yet by the time 3.0 comes)? Or do we assme that an idea we agree enough on to add to this document would all be ready to be implemented by 3.0? > +### Changes > + > + - The default initial branch name will be changed from "master" to "main". > + > + Cf. , > + . Forcing readers to read entire threads for these two discussions somehow feels brutal at least to me. And reading only these two individual messages does not give readers much insight. Saying "this was discussed in the past in late 2020, and because major hosting sites give 'main' as the initial branch by default for new users unless configured these days, we will match to avoid end user confusion", if we want to explain why we are changing it, should be sufficient. But seeing that the other two items below do not have any such explanation, we may be better of not having it here, perhaps? I take this iteration to illustrate the format of items (and what kinds of items) we want to have in the document. If the proposal made by the above item is: Once we have a discussion thread that shows clear concensus (neither of the above two are not), we'd record the decision and have a reference to the thread. then I 100% agree with the plan for this document. > + - The default hash function for new repositories will be changed from "sha1" > + to "sha256". > + > + - The default ref backend for new repositories will be changed from "files" to > + "reftable". > + > +### Removals > + > + - git-http-push(1) can be used to push objects to a remote repository via > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > + nowadays anymore and will be removed together with the command. > + > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > + server like Apache. The protocol has not seen any updates recently and is > + neither compatible with alternative hash functions nor with alternative ref > + backends. It will thus be removed. > + > + - git-update-server-info(1) generates data required when serving data via the > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > + anymore and will be removed together with the protocol. This includes the > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > + `git repack -n` flag. > + > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > + concept has long been replaced by remotes and will thus be removed. "remotes" -> "the 'remotes.*.*' configuration variables", perhaps? > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > + HTTP server. These scripts have been unmaintained for a significant amount of > + time and will be removed. Do we want to give plausible alternatives (or merely hinting existence of alternatives might be sufficient)? > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > + very slow, hard to use and has many gotchas. It will thus be removed in favor > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > + > + - The "dashed form", i.e. support for calling `git-` instead of > + `git ` in scripts, has been deprecated for a long time and will be > + removed. I find this questionable but as you said, we'll start from skeletal form of this document (without any items), have discussion thread on each of these items, and add back those we have concensus on, so I'll not further talk about this item in this message. > + - The command to import patches from Quilt seems to be used rarely, if > + ever, and will be removed. Not limited to this item, but do we want to mention in this document how we measured the actual usage, which we base our deprecation decision on? I do not think such a comment should be attached to each of these items (this one and the next one are proposed for the same reason),... > + - Support for importing repositories from GNU Arch will be removed because > + it would not appear to have any users. ... but in a preamble of the document, e.g., "methodology and criteria we used to propose these removals". Random ideas that may or may not work: - debian popcon? - google trends, counting the appearance of queries? - telemetry from commands that call home (we do not have any)? > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The action flags will not be removed in the next major Git > + release as there likely exist a lot of scripts out there that use the old > + syntax. > + > + Cf. . This is a good example of "we had a concensus back when this was discussed; see the thread this message is on". I think it would be beneficial to write down what these references _mean_ at the beginning of the document, e.g. When this document refers to a message-ID, you can visit 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 that the project reached concensus on the described item back then. As this is a living document, and 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 these references to mean "it is settled, do not waste our time bringing it up again". or something like that. Thanks. ``` ## Patrick Steinhardt, 2024-05-30 12:04 Subject: Re: [PATCH v3] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZlhrY6y829bcHVoZ%40tanuki In-Reply-To: ``` On Fri, May 24, 2024 at 10:27:13AM -0700, Junio C Hamano wrote: > Patrick Steinhardt writes: > > > case, most of the proposed deprecations didn't get much pushback. I'm > > less sure whether this is because people didn't look, or because they > > silently agree with what I propose for deprecation. > > Or because I explicitly said that first we'll brainstorm, in order > to encourage generation of more ideas, without shooting other > people's ideas down? Fair, I guess. [snip] > > +## Git 3.0 > > Question. > > Will we have "## Git 4.0" etc., to indicate the timelines (some > stuff we might eventually replace/change, but we may not ready yet > by the time 3.0 comes)? Or do we assme that an idea we agree enough > on to add to this document would all be ready to be implemented by > 3.0? Good question. For now I have added such items to the "Superseded features that will not be deprecated" section, with a hint that we may revisit the deprecation in the future. E.g. for the git-config(1) actions I say the following: The action flags will not be removed in the next major Git release as there likely exist a lot of scripts out there that use the old syntax. I think that this is easiest to manage for other features where we are not yet ready to commit to a deprecation, as well, due to whatever reason. Those items can be added along with a condition that, once met, may prompt us to revisit a deprecation. > > +### Changes > > + > > + - The default initial branch name will be changed from "master" to "main". > > + > > + Cf. , > > + . > > Forcing readers to read entire threads for these two discussions > somehow feels brutal at least to me. And reading only these two > individual messages does not give readers much insight. > > Saying "this was discussed in the past in late 2020, and because > major hosting sites give 'main' as the initial branch by default for > new users unless configured these days, we will match to avoid end > user confusion", if we want to explain why we are changing it, > should be sufficient. But seeing that the other two items below do > not have any such explanation, we may be better of not having it > here, perhaps? > > I take this iteration to illustrate the format of items (and what > kinds of items) we want to have in the document. If the proposal > made by the above item is: > > Once we have a discussion thread that shows clear concensus > (neither of the above two are not), we'd record the decision and > have a reference to the thread. > > then I 100% agree with the plan for this document. Yes, that's my intent. The bullet item should be self-explaining, potentially with one or two sentences explaining why. The reference to the mailing list thread is supposed to give a pointer where, when and why this decision was made so that people can revisit the discussion. So the two bullet points below are certainly quite lazy because they do not provide any context whatsoever. > > + - The default hash function for new repositories will be changed from "sha1" > > + to "sha256". > > + > > + - The default ref backend for new repositories will be changed from "files" to > > + "reftable". > > + > > +### Removals > > + > > + - git-http-push(1) can be used to push objects to a remote repository via > > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > > + nowadays anymore and will be removed together with the command. > > + > > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > > + server like Apache. The protocol has not seen any updates recently and is > > + neither compatible with alternative hash functions nor with alternative ref > > + backends. It will thus be removed. > > + > > + - git-update-server-info(1) generates data required when serving data via the > > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > > + anymore and will be removed together with the protocol. This includes the > > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > > + `git repack -n` flag. > > + > > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > > + concept has long been replaced by remotes and will thus be removed. > > "remotes" -> "the 'remotes.*.*' configuration variables", perhaps? > > > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > > + HTTP server. These scripts have been unmaintained for a significant amount of > > + time and will be removed. > > Do we want to give plausible alternatives (or merely hinting > existence of alternatives might be sufficient)? I guess that would be solutions like cgit, right? While those recommendations may go stale over time, I still think it'd be worthwhile to help our users in case they do rely on any deprecated feature. > > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > > + very slow, hard to use and has many gotchas. It will thus be removed in favor > > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > > + > > + - The "dashed form", i.e. support for calling `git-` instead of > > + `git ` in scripts, has been deprecated for a long time and will be > > + removed. > > I find this questionable but as you said, we'll start from skeletal > form of this document (without any items), have discussion thread on > each of these items, and add back those we have concensus on, so > I'll not further talk about this item in this message. I'd propose to have one (hopefully uncontroversial) item per section just to demonstrate how the format is supposed to look like. But other than that I'm happy to drop most of these items. > > + - The command to import patches from Quilt seems to be used rarely, if > > + ever, and will be removed. > > Not limited to this item, but do we want to mention in this document > how we measured the actual usage, which we base our deprecation > decision on? I do not think such a comment should be attached to > each of these items (this one and the next one are proposed for the > same reason),... > > > + - Support for importing repositories from GNU Arch will be removed because > > + it would not appear to have any users. > > ... but in a preamble of the document, e.g., "methodology and > criteria we used to propose these removals". Random ideas that may > or may not work: > > - debian popcon? > - google trends, counting the appearance of queries? > - telemetry from commands that call home (we do not have any)? That would certainly be helpful to give us a better base to argue. > > + - git-config(1) has learned to use subcommands that replace implicit actions > > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > > + --unset-all`). The action flags will not be removed in the next major Git > > + release as there likely exist a lot of scripts out there that use the old > > + syntax. > > + > > + Cf. . > > This is a good example of "we had a concensus back when this was > discussed; see the thread this message is on". I think it would be > beneficial to write down what these references _mean_ at the beginning > of the document, e.g. > > When this document refers to a message-ID, you can visit > > 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 that the > project reached concensus on the described item back then. As > this is a living document, and 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 these references to mean "it is settled, do not > waste our time bringing it up again". > > or something like that. Good idea, will do. Patrick ``` ## Patrick Steinhardt, 2024-05-31 07:56 Subject: [PATCH v4 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/cover.1717141598.git.ps%40pks.im In-Reply-To: ``` Hi, this is the fourth version of my patch series that documents upcoming breaking changes. I have restructured this series now, booting out most of the proposed deprecations. This is not because I think that those deprecations shouldn't be done, but merely to bring this series into a format that can be merged. The first patch introduces the document in a skeletal form. The next three patches then introduce one item each to the three sections that we have in this document. The intent of this is to start out with examples of how this should look like. I have tried to pick topics which may be the least controversial ones for each of those sections while still being interesting enough to demonstrate the proposed format. Let's see whether I succeeded with that goal :) As said, I do not have the intent to shut down any of the other proposed deprecations. When this document lands, I'd encourage folks to propose their deprecations in standalone threads, ideally together with a patch to "BreakingChanges.md". You may have noticed that I dropped the "Upcoming" prefix from "UpcomingBreakingChanges.md". This is supposed to reflect the fact that we also have a section that point out features that we are _not_ deprecating. Those aren't upcoming, so I thought a rename makes sense. 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.md | 113 +++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 Documentation/BreakingChanges.md base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-05-31 07:56 Subject: [PATCH v4 1/4] docs: introduce document to announce breaking changes Message-ID: <993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps@pks.im> URL: https://gitlist.dev/e/993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps%40pks.im In-Reply-To: ``` 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 --- 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 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. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-05-31 07:56 Subject: [PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: <7c84b2f957595a3d8bc6d28970a009339c5fbf5c.1717141598.git.ps@pks.im> URL: https://gitlist.dev/e/7c84b2f957595a3d8bc6d28970a009339c5fbf5c.1717141598.git.ps%40pks.im In-Reply-To: ``` Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely. Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0. All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md index d8a26c9bf9..1b0a357e65 100644 --- a/Documentation/BreakingChanges.md +++ b/Documentation/BreakingChanges.md @@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already. ### Changes + - The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: + + - The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + + - SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + + - Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + + - Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. + + While we have protections in place against known attacks, it is expected + that more attacks against SHA-1 will be found by future research. Paired + with the ever-growing capability of hardware, it is only a matter of time + before SHA-1 will be considered broken completely. We want to be prepared + and will thus change the default hash algorithm to "sha256" for newly + initialized repositories. + + Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, + <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, + . + ### Removals ## Superseded features that will not be deprecated -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-05-31 07:56 Subject: [PATCH v4 3/4] BreakingChanges: document removal of grafting Message-ID: <91d78490c2358b417e32694d8dc125b93a4e389d.1717141598.git.ps@pks.im> URL: https://gitlist.dev/e/91d78490c2358b417e32694d8dc125b93a4e389d.1717141598.git.ps%40pks.im In-Reply-To: ``` The grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs. Follow through with the deprecation and mark grafts for removal in Git 3.0. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md index 1b0a357e65..14c0972b08 100644 --- a/Documentation/BreakingChanges.md +++ b/Documentation/BreakingChanges.md @@ -85,6 +85,14 @@ be changed to or replaced in case the alternative was implemented already. ### 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. + + Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + ## Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-05-31 07:56 Subject: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: <40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps@pks.im> URL: https://gitlist.dev/e/40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps%40pks.im In-Reply-To: ``` The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions. This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. Document that neither of these commands will not go away anytime soon. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md index 14c0972b08..fb2c8ddf5a 100644 --- a/Documentation/BreakingChanges.md +++ b/Documentation/BreakingChanges.md @@ -99,3 +99,15 @@ 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. + + - 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. + + This decision may get revisited in case we ever figure out that there are + almost no users of any of the commands anymore. + + Cf. , + , + <112b6568912a6de6672bf5592c3a718e@manjaro.org>. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Junio C Hamano, 2024-05-31 08:43 Subject: Re: [PATCH v4 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqr0dijrrh.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: > You may have noticed that I dropped the "Upcoming" prefix from > "UpcomingBreakingChanges.md". This is supposed to reflect the fact that > we also have a section that point out features that we are _not_ > deprecating. Those aren't upcoming, so I thought a rename makes sense. I do not mind missing upcoming, but why markdown? The mark-up we as the project chose is AsciiDoc and unless there is a compelling reason to use something else, we should stick to it. Yes, README.md is not AsciiDoc but that is primarily because what GitHub does on the project page. ``` ## Patrick Steinhardt, 2024-05-31 11:15 Subject: Re: [PATCH v4 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/ZlmxaNF94XbaTxxY%40tanuki In-Reply-To: ``` On Fri, May 31, 2024 at 01:43:30AM -0700, Junio C Hamano wrote: > Patrick Steinhardt writes: > > > You may have noticed that I dropped the "Upcoming" prefix from > > "UpcomingBreakingChanges.md". This is supposed to reflect the fact that > > we also have a section that point out features that we are _not_ > > deprecating. Those aren't upcoming, so I thought a rename makes sense. > > I do not mind missing upcoming, but why markdown? The mark-up we as > the project chose is AsciiDoc and unless there is a compelling reason > to use something else, we should stick to it. > > Yes, README.md is not AsciiDoc but that is primarily because what > GitHub does on the project page. Oh well, fair enough. I'll convert it to AsciiDoc in the next version, but will wait a bit longer for feedback. Thanks! Patrick ``` ## Junio C Hamano, 2024-05-31 16:51 Subject: Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqr0dhgc1e.fsf%40gitster.g In-Reply-To: <993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps@pks.im> ``` Patrick Steinhardt 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 > --- > 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. ``` ## Junio C Hamano, 2024-05-31 17:00 Subject: Re: [PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/xmqqikytgbmc.fsf%40gitster.g In-Reply-To: <7c84b2f957595a3d8bc6d28970a009339c5fbf5c.1717141598.git.ps@pks.im> ``` Patrick Steinhardt writes: > Let's plan for this event by being active instead of waiting for it to > happend and announce that the default object format is going to change > from "sha1" to "sha256" with Git 3.0. "happened" -> "happen," > All major Git implementations (libgit2, JGit, go-git) support the > "sha256" object format and are thus prepared for this change. The most > important missing piece in the puzzle is support in forges. But while > GitLab recently gained experimental support for the "sha256" object > format though, to the best of my knowledge GitHub doesn't support it > yet. Ideally, announcing this upcoming change will encourage forges to > start building that support. ;-) Nevertheless, we probably want some of that in the body text. > Signed-off-by: Patrick Steinhardt > --- > Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++ > 1 file changed, 27 insertions(+) > > diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md > index d8a26c9bf9..1b0a357e65 100644 > --- a/Documentation/BreakingChanges.md > +++ b/Documentation/BreakingChanges.md > @@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already. > > ### Changes > > + - The default hash function for new repositories will be changed from "sha1" > + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays > + recommended against in FIPS 140-2 and similar certifications. Furthermore, > + there are practical attacks on SHA-1 that weaken its cryptographic properties: > + > + - The SHAppening (2015). The first demonstration of a practical attack > + against SHA-1 with 2^57 operations. > + > + - SHAttered (2017). Generation of two valid PDF files with 2^63 operations. > + > + - Birthday-Near-Collision (2019). This attack allows for chosen prefix > + attacks with 2^68 operations. > + > + - Shambles (2020). This attack allows for chosen prefix attacks with 2^63 > + operations. > + > + While we have protections in place against known attacks, it is expected > + that more attacks against SHA-1 will be found by future research. Paired > + with the ever-growing capability of hardware, it is only a matter of time > + before SHA-1 will be considered broken completely. We want to be prepared > + and will thus change the default hash algorithm to "sha256" for newly > + initialized repositories. > + > + Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, > + <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, > + . We probably need to at least briefly mention external constraints here. Even though in our ideal world, what we say here will force others like GitHub to follow, in the real world that is not always the case. As this particular commit is about establishing the pattern, expected form of each entry, how about adding convention to have a paragraph on "foreseen risks", in addition to the "what we plan to do", and "why we want to go there" we see above? > ### Removals > > ## Superseded features that will not be deprecated Thanks. ``` ## Junio C Hamano, 2024-05-31 17:05 Subject: Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: URL: https://gitlist.dev/e/xmqqcyp1gbej.fsf%40gitster.g In-Reply-To: <40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps@pks.im> ``` Patrick Steinhardt writes: > The git-checkout(1) command is seen by many as hard to understand > because it connects two somewhat unrelated features: switching between > branches and restoring worktree files from arbitrary revisions. In 2019, > we thus implemented two new commands git-switch(1) and git-restore(1) to > split out these separate concerns into standalone functions. > > This "replacement" of git-checkout(1) has repeatedly triggered concerns > for our userbase that git-checkout(1) will eventually go away. This is > not the case though: the use of that command is still widespread, and it > is not expected that this will change anytime soon. > > Document that neither of these commands will not go away anytime soon. "neither" -> "none"? It is accepted to use neither to pick among three things these days, but the latter is clearer. ``` ## Todd Zullinger, 2024-05-31 23:35 Subject: Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: URL: https://gitlist.dev/e/Zlpe0lOjR45gXYXI%40teonanacatl.net In-Reply-To: ``` Junio C Hamano wrote: > Patrick Steinhardt writes: > >> The git-checkout(1) command is seen by many as hard to understand >> because it connects two somewhat unrelated features: switching between >> branches and restoring worktree files from arbitrary revisions. In 2019, >> we thus implemented two new commands git-switch(1) and git-restore(1) to >> split out these separate concerns into standalone functions. >> >> This "replacement" of git-checkout(1) has repeatedly triggered concerns >> for our userbase that git-checkout(1) will eventually go away. This is >> not the case though: the use of that command is still widespread, and it >> is not expected that this will change anytime soon. >> >> Document that neither of these commands will not go away anytime soon. > > "neither" -> "none"? It is accepted to use neither to pick among > three things these days, but the latter is clearer. I think 'will not' should lose the 'not' as well: Document that neither|none of these commands will go away anytime soon. Alternately, the neither/none question could be resolved by dropping it entirely: Document that these commands will not go away anytime soon. I'm not sure that's better; it leaves ambiguity about what "these commands" includes. Maybe: Document that all three commands will remain for the foreseeable future. But after writing all that, I only just noticed this is in the commit message. And while that's important, the more important content of the change itself uses clear language to say all three commands will stay. :) -- Todd ``` ## Patrick Steinhardt, 2024-06-03 09:28 Subject: [PATCH v5 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/cover.1717402497.git.ps%40pks.im In-Reply-To: ``` Hi, this is another iteration of my patch series that intends to start tracking upcoming breaking changes in Git. Changes compared to v4: - Converted the document to use AsciiDoc instead of MarkDown. - Reword "major release" to "breaking release". - Note Git 2.0, which is the last major breaking release. - Note that minor bug fixes that lead to user visible changes in behavior do not require a breaking release. - Clarify that misdesigned features may be removed without replacement, if necessary. - Fix double negation in commit message of the last commit. 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 | 115 ++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 Documentation/BreakingChanges.txt Range-diff against v4: 1: 993b936348 ! 1: 67cb4de5cb docs: introduce document to announce breaking changes @@ Commit message Signed-off-by: Patrick Steinhardt - ## Documentation/BreakingChanges.md (new) ## + ## Documentation/BreakingChanges.txt (new) ## @@ -+# Upcoming breaking changes ++= 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 @@ Documentation/BreakingChanges.md (new) +required to keep the project aligned with a changing world. These changes fall +into several categories: + -+ - Changes to long established defaults. ++* 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. + -+ - Concepts that have been replaced with a superior design. ++Explicitly not included in this list are fixes to minor bugs that may cause a ++change in user-visible behavior. + -+ - Concepts, commands, configuration or options that have been lacking in major -+ ways and that cannot be fixed. ++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: + -+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. ++* 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 @@ Documentation/BreakingChanges.md (new) +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, ++make the described change. 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.md (new) +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 ++== 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. ++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 ++=== Changes + -+### Removals ++=== Removals + -+## Superseded features that will not be deprecated ++== 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. ++those features with newer alternatives. 2: 7c84b2f957 ! 2: b36ffcbaa6 BreakingChanges: document upcoming change from "sha1" to "sha256" @@ Commit message Signed-off-by: Patrick Steinhardt - ## Documentation/BreakingChanges.md ## -@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already. + ## Documentation/BreakingChanges.txt ## +@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alternative was implemented already. - ### Changes + === Changes -+ - The default hash function for new repositories will be changed from "sha1" -+ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays -+ recommended against in FIPS 140-2 and similar certifications. Furthermore, -+ there are practical attacks on SHA-1 that weaken its cryptographic properties: ++* The default hash function for new repositories will be changed from "sha1" ++ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays ++ recommended against in FIPS 140-2 and similar certifications. Furthermore, ++ there are practical attacks on SHA-1 that weaken its cryptographic properties: +++ ++ ** The SHAppening (2015). The first demonstration of a practical attack ++ against SHA-1 with 2^57 operations. ++ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. ++ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix ++ attacks with 2^68 operations. ++ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 ++ operations. +++ ++While we have protections in place against known attacks, it is expected ++that more attacks against SHA-1 will be found by future research. Paired ++with the ever-growing capability of hardware, it is only a matter of time ++before SHA-1 will be considered broken completely. We want to be prepared ++and will thus change the default hash algorithm to "sha256" for newly ++initialized repositories. +++ ++Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, ++<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, ++. + -+ - The SHAppening (2015). The first demonstration of a practical attack -+ against SHA-1 with 2^57 operations. -+ -+ - SHAttered (2017). Generation of two valid PDF files with 2^63 operations. -+ -+ - Birthday-Near-Collision (2019). This attack allows for chosen prefix -+ attacks with 2^68 operations. -+ -+ - Shambles (2020). This attack allows for chosen prefix attacks with 2^63 -+ operations. -+ -+ While we have protections in place against known attacks, it is expected -+ that more attacks against SHA-1 will be found by future research. Paired -+ with the ever-growing capability of hardware, it is only a matter of time -+ before SHA-1 will be considered broken completely. We want to be prepared -+ and will thus change the default hash algorithm to "sha256" for newly -+ initialized repositories. -+ -+ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, -+ <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, -+ . -+ - ### Removals + === Removals - ## Superseded features that will not be deprecated + == Superseded features that will not be deprecated 3: 91d78490c2 ! 3: 4142e472ac BreakingChanges: document removal of grafting @@ Commit message Signed-off-by: Patrick Steinhardt - ## Documentation/BreakingChanges.md ## -@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already. + ## Documentation/BreakingChanges.txt ## +@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, - ### Removals + === 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. ++* 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. +++ ++Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + -+ Cf. <20140304174806.GA11561@sigill.intra.peff.net>. -+ - ## Superseded features that will not be deprecated + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in 4: 40594bda5c ! 4: 9ff94b6f32 BreakingChanges: document that we do not plan to deprecate git-checkout @@ Commit message not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. - Document that neither of these commands will not go away anytime soon. + Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt - ## Documentation/BreakingChanges.md ## -@@ Documentation/BreakingChanges.md: Some features have gained newer replacements that aim to improve the design in + ## Documentation/BreakingChanges.txt ## +@@ Documentation/BreakingChanges.txt: 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. + 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. -+ -+ This decision may get revisited in case we ever figure out that there are -+ almost no users of any of the commands anymore. -+ -+ Cf. , -+ , -+ <112b6568912a6de6672bf5592c3a718e@manjaro.org>. ++* 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. +++ ++This decision may get revisited in case we ever figure out that there are ++almost no users of any of the commands anymore. +++ ++Cf. , ++, ++<112b6568912a6de6672bf5592c3a718e@manjaro.org>. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-03 09:28 Subject: [PATCH v5 1/4] docs: introduce document to announce breaking changes Message-ID: <67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im> URL: https://gitlist.dev/e/67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps%40pks.im In-Reply-To: ``` 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 --- Documentation/BreakingChanges.txt | 71 +++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 Documentation/BreakingChanges.txt diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt new file mode 100644 index 0000000000..ddce7cc301 --- /dev/null +++ b/Documentation/BreakingChanges.txt @@ -0,0 +1,71 @@ += 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 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 +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, +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 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. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-03 09:28 Subject: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/b36ffcbaa67dcdada630e2d582e75da623512743.1717402497.git.ps%40pks.im In-Reply-To: ``` Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely. Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0. All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index ddce7cc301..904857a636 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, +. + === Removals == Superseded features that will not be deprecated -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-03 09:28 Subject: [PATCH v5 3/4] BreakingChanges: document removal of grafting Message-ID: <4142e472ac54f5008b0566fdb967f86677171491.1717402497.git.ps@pks.im> URL: https://gitlist.dev/e/4142e472ac54f5008b0566fdb967f86677171491.1717402497.git.ps%40pks.im In-Reply-To: ``` The grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs. Follow through with the deprecation and mark grafts for removal in Git 3.0. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 904857a636..b5088dcce2 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, === 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. ++ +Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-03 09:28 Subject: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: <9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps@pks.im> URL: https://gitlist.dev/e/9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps%40pks.im In-Reply-To: ``` The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions. This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index b5088dcce2..3c38676f49 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -101,3 +101,15 @@ 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. + +* 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. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-03 09:32 Subject: Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/Zl2Np9qNcA6Z1q5U%40framework In-Reply-To: ``` On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote: > Patrick Steinhardt 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 ``` ## Phillip Wood, 2024-06-03 14:08 Subject: Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/c2129c09-dd71-4cc7-802c-bf662db93435%40gmail.com In-Reply-To: <67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im> ``` Hi Patrick Thanks for working on this, I've left a couple of small comments below but I'm not sure they're worth a re-roll on their own. All of the patches look sensible to me. On 03/06/2024 10:28, Patrick Steinhardt wrote: > +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 > +make the described change. "self-sufficient explanation" strikes me as a slightly add turn of phrase, maybe something like 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. 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". We could possibly add "If circumstances change" to the start of the second sentence to discourage repeated discussions of the same issue when someone has a bee in their bonnet about a particular change but I think we can probably handle that on the mailing list without any changes here. Best Wishes Phillip ``` ## Junio C Hamano, 2024-06-03 16:17 Subject: Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqq34pu6lwm.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt 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/ ``` ## Junio C Hamano, 2024-06-03 16:24 Subject: Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqv82q56zz.fsf%40gitster.g In-Reply-To: <67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im> ``` Patrick Steinhardt writes: > +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. "next major Git release" -> "future breaking release(s)". I do not know offhand if we want to plan for longer timespans that may cover multiple breaking releases, hence (s) in parentheses. "documente" -> "document". > +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". But you are expected to be aware of past discussion, and if you are not bringing anything new to the table, you are wasting our time. Note that pointing out an old rationale no longer applies to today's world still counts as a new datapoint in a renewed discussion. ``` ## Junio C Hamano, 2024-06-03 16:36 Subject: Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/xmqqfrtu56fo.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: > Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, > 2023-07-31), the "sha256" object format is no longer considered to be > experimental. Furthermore, the SHA-1 hash function is actively > recommended against by for example NIST and FIPS 140-2, and attacks > against it are becoming more practical both due to new weaknesses > (SHAppening, SHAttered, Shambles) and due to the ever-increasing > computing power. It is only a matter of time before it can be considered > to be broken completely. > > Let's plan for this event by being active instead of waiting for it to > happend and announce that the default object format is going to change > from "sha1" to "sha256" with Git 3.0. > > All major Git implementations (libgit2, JGit, go-git) support the > "sha256" object format and are thus prepared for this change. The most > important missing piece in the puzzle is support in forges. But while > GitLab recently gained experimental support for the "sha256" object > format though, to the best of my knowledge GitHub doesn't support it > yet. Ideally, announcing this upcoming change will encourage forges to > start building that support. > > Signed-off-by: Patrick Steinhardt > --- > Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ > 1 file changed, 24 insertions(+) > > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt > index ddce7cc301..904857a636 100644 > --- a/Documentation/BreakingChanges.txt > +++ b/Documentation/BreakingChanges.txt > @@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. > > === Changes > > +* The default hash function for new repositories will be changed from "sha1" > + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays > + recommended against in FIPS 140-2 and similar certifications. Furthermore, > + there are practical attacks on SHA-1 that weaken its cryptographic properties: > ++ > + ** The SHAppening (2015). The first demonstration of a practical attack > + against SHA-1 with 2^57 operations. > + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. > + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix > + attacks with 2^68 operations. > + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 > + operations. > ++ > +While we have protections in place against known attacks, it is expected > +that more attacks against SHA-1 will be found by future research. Paired > +with the ever-growing capability of hardware, it is only a matter of time > +before SHA-1 will be considered broken completely. We want to be prepared > +and will thus change the default hash algorithm to "sha256" for newly > +initialized repositories. > ++ > +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, > +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, > +. A few things we should probably list are: - Even if you can locally use SHA-256 in your project and push/fetch the history around, public forges may not be ready. - The strategy to migrate existing SHA-1 project to SHA-256 without going through a flag day change has been designed but not implemented or deployed. - This is only about the change of the default; we currently have no plan to drop support for SHA-1 repositories. IMHO, we would want each and every item in this document to mention the risk factors that may prevent us from going forward even if we wanted to, and the first item above is an example. Thanks. ``` ## Junio C Hamano, 2024-06-03 16:42 Subject: Re: [PATCH v5 3/4] BreakingChanges: document removal of grafting Message-ID: URL: https://gitlist.dev/e/xmqq8qzm566y.fsf%40gitster.g In-Reply-To: <4142e472ac54f5008b0566fdb967f86677171491.1717402497.git.ps@pks.im> ``` Patrick Steinhardt writes: > The grafting mechanism for objects has been deprecated in e650d0643b > (docs: mark info/grafts as outdated, 2014-03-05), which is more than a > decade ago. The mechanism can lead to hard-to-debug issues and has a > superior replacement with replace refs. > > Follow through with the deprecation and mark grafts for removal in Git > 3.0. > > Signed-off-by: Patrick Steinhardt > --- > Documentation/BreakingChanges.txt | 8 ++++++++ > 1 file changed, 8 insertions(+) > > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt > index 904857a636..b5088dcce2 100644 > --- a/Documentation/BreakingChanges.txt > +++ b/Documentation/BreakingChanges.txt > @@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, > > === 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. The replace refs will be transferred, but the graft is a purely local mechanism and there is no way (other than by human intervention) to communicate the graft entries across repositories. That is the primary thing we should list as the reason why the replace mechanism is a better alternative over the graft mechanism. > + They have been outdated since e650d0643b (docs: mark info/grafts as outdated, > + 2014-03-05) and will be removed. > ++ > +Cf. <20140304174806.GA11561@sigill.intra.peff.net>. > + > == Superseded features that will not be deprecated > > Some features have gained newer replacements that aim to improve the design in ``` ## Junio C Hamano, 2024-06-03 16:52 Subject: Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: URL: https://gitlist.dev/e/xmqqo78i3r5a.fsf%40gitster.g In-Reply-To: <9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps@pks.im> ``` Patrick Steinhardt writes: > + > +* 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. "As a replacement" is probably a bit different from the truth [*], but I suspect that the reason why they were introduced no longer has much relevance. How about 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. or something (borrowing from your proposed log message)? [Footnote] * If we were to mention the history behind the introduction, we'd end up saying: as an experiment, we introduced the pair of commands that do different half of the original command to see if they can replace the original. The decision to keep the original would lead to implication that this was a failed experiment, which makes people (unnecessarily) wonder if the failed experiment should be removed. I am trying to avoid such unnecessary implication here. ``` ## Patrick Steinhardt, 2024-06-04 06:59 Subject: Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/Zl67SnAQbtnxzAxS%40framework In-Reply-To: ``` On Mon, Jun 03, 2024 at 09:24:48AM -0700, Junio C Hamano wrote: > Patrick Steinhardt writes: > > +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". > > But you are expected to be aware of past discussion, and if you are > not bringing anything new to the table, you are wasting our time. > Note that pointing out an old rationale no longer applies to today's > world still counts as a new datapoint in a renewed discussion. Yeah. I like Phillip's proposal here, which adds "If circumstances change" to the second sentence to clarify that we do not want to rehash the same arguments. Patrick ``` ## Patrick Steinhardt, 2024-06-04 07:06 Subject: Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/Zl682Dk6RcFOC2rA%40framework In-Reply-To: ``` On Mon, Jun 03, 2024 at 09:36:59AM -0700, Junio C Hamano wrote: > Patrick Steinhardt writes: > > > Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, > > 2023-07-31), the "sha256" object format is no longer considered to be > > experimental. Furthermore, the SHA-1 hash function is actively > > recommended against by for example NIST and FIPS 140-2, and attacks > > against it are becoming more practical both due to new weaknesses > > (SHAppening, SHAttered, Shambles) and due to the ever-increasing > > computing power. It is only a matter of time before it can be considered > > to be broken completely. > > > > Let's plan for this event by being active instead of waiting for it to > > happend and announce that the default object format is going to change > > from "sha1" to "sha256" with Git 3.0. > > > > All major Git implementations (libgit2, JGit, go-git) support the > > "sha256" object format and are thus prepared for this change. The most > > important missing piece in the puzzle is support in forges. But while > > GitLab recently gained experimental support for the "sha256" object > > format though, to the best of my knowledge GitHub doesn't support it > > yet. Ideally, announcing this upcoming change will encourage forges to > > start building that support. > > > > Signed-off-by: Patrick Steinhardt > > --- > > Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ > > 1 file changed, 24 insertions(+) > > > > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt > > index ddce7cc301..904857a636 100644 > > --- a/Documentation/BreakingChanges.txt > > +++ b/Documentation/BreakingChanges.txt > > @@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. > > > > === Changes > > > > +* The default hash function for new repositories will be changed from "sha1" > > + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays > > + recommended against in FIPS 140-2 and similar certifications. Furthermore, > > + there are practical attacks on SHA-1 that weaken its cryptographic properties: > > ++ > > + ** The SHAppening (2015). The first demonstration of a practical attack > > + against SHA-1 with 2^57 operations. > > + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. > > + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix > > + attacks with 2^68 operations. > > + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 > > + operations. > > ++ > > +While we have protections in place against known attacks, it is expected > > +that more attacks against SHA-1 will be found by future research. Paired > > +with the ever-growing capability of hardware, it is only a matter of time > > +before SHA-1 will be considered broken completely. We want to be prepared > > +and will thus change the default hash algorithm to "sha256" for newly > > +initialized repositories. > > ++ > > +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, > > +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, > > +. > > A few things we should probably list are: > > - Even if you can locally use SHA-256 in your project and > push/fetch the history around, public forges may not be ready. > > - The strategy to migrate existing SHA-1 project to SHA-256 without > going through a flag day change has been designed but not > implemented or deployed. > > - This is only about the change of the default; we currently have > no plan to drop support for SHA-1 repositories. > > IMHO, we would want each and every item in this document to mention > the risk factors that may prevent us from going forward even if we > wanted to, and the first item above is an example. > > Thanks. I agree that explicitly mentioning (1) and (3) is sensible. Is the second one important though given that this is about the default when creating _new_ repositories? I don't think interop code is a requirement to make "sha256" the default, is it? Patrick ``` ## Patrick Steinhardt, 2024-06-04 07:11 Subject: Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: URL: https://gitlist.dev/e/Zl6-IXA_REOy05wh%40framework In-Reply-To: ``` On Mon, Jun 03, 2024 at 09:52:33AM -0700, Junio C Hamano wrote: > Patrick Steinhardt writes: > > > + > > +* 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. > > "As a replacement" is probably a bit different from the truth [*], > but I suspect that the reason why they were introduced no longer has > much relevance. How about > > 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. > > or something (borrowing from your proposed log message)? Fair enough, let's add it like this. Thanks! Patrick ``` ## Patrick Steinhardt, 2024-06-04 07:42 Subject: Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/Zl7FdB2juCFkHuba%40framework In-Reply-To: ``` On Mon, Jun 03, 2024 at 09:17:29AM -0700, Junio C Hamano wrote: > Patrick Steinhardt 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 ``` ## Patrick Steinhardt, 2024-06-04 12:32 Subject: [PATCH v6 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/cover.1717504292.git.ps%40pks.im In-Reply-To: ``` 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>, +. 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. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-04 12:32 Subject: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/a260bbf281d2975562a042a71ca0dd7f88f03da4.1717504292.git.ps%40pks.im In-Reply-To: ``` 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 --- Documentation/BreakingChanges.txt | 74 +++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 Documentation/BreakingChanges.txt 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. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-04 12:32 Subject: [PATCH v6 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/f7c6a66f7180a4d469fa269b1be3991b98f36c66.1717504292.git.ps%40pks.im In-Reply-To: ``` Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely. Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0. All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 36327b13b8..5d7e80aebb 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -64,6 +64,36 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +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>, +. + === Removals == Superseded features that will not be deprecated -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-04 12:32 Subject: [PATCH v6 3/4] BreakingChanges: document removal of grafting Message-ID: URL: https://gitlist.dev/e/b25b91a5e707f671785012c1b4a68c36241e537e.1717504292.git.ps%40pks.im In-Reply-To: ``` The grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs. Follow through with the deprecation and mark grafts for removal in Git 3.0. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 5d7e80aebb..9fb6d8c78a 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, === Removals +* 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 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>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in -- 2.45.1.410.g58bac47f8e.dirty ``` ## Patrick Steinhardt, 2024-06-04 12:32 Subject: [PATCH v6 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: <4fafccc3b919d68c51f83b2cb0c04f8621c17426.1717504292.git.ps@pks.im> URL: https://gitlist.dev/e/4fafccc3b919d68c51f83b2cb0c04f8621c17426.1717504292.git.ps%40pks.im In-Reply-To: ``` The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions. This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 9fb6d8c78a..0fd60a7776 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -114,3 +114,15 @@ 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. + +* 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. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. -- 2.45.1.410.g58bac47f8e.dirty ``` ## Phillip Wood, 2024-06-04 14:23 Subject: Re: [PATCH v6 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/f231d5ff-08e5-47b3-aadc-0f88566c2588%40gmail.com In-Reply-To: ``` Hi Patrick On 04/06/2024 13:32, Patrick Steinhardt wrote: > 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. This version looks good to me Thanks for writing this document Phillip > 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>, > +. > 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. ``` ## Junio C Hamano, 2024-06-04 17:16 Subject: Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/xmqqtti8wruz.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: > I agree that explicitly mentioning (1) and (3) is sensible. Is the > second one important though given that this is about the default when > creating _new_ repositories? I don't think interop code is a requirement > to make "sha256" the default, is it? Let's drop (2) from the list, as I do not think there ever was a concensus on it, and also for the sake of brevity. Thanks. ``` ## Junio C Hamano, 2024-06-04 17:59 Subject: Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqsexsvbaf.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt 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". ``` ## Junio C Hamano, 2024-06-04 18:00 Subject: Re: [PATCH v6 3/4] BreakingChanges: document removal of grafting Message-ID: URL: https://gitlist.dev/e/xmqqo78gvb9w.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: > The grafting mechanism for objects has been deprecated in e650d0643b > (docs: mark info/grafts as outdated, 2014-03-05), which is more than a > decade ago. The mechanism can lead to hard-to-debug issues and has a > superior replacement with replace refs. > > Follow through with the deprecation and mark grafts for removal in Git > 3.0. > > Signed-off-by: Patrick Steinhardt > --- > Documentation/BreakingChanges.txt | 12 ++++++++++++ > 1 file changed, 12 insertions(+) > > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt > index 5d7e80aebb..9fb6d8c78a 100644 > --- a/Documentation/BreakingChanges.txt > +++ b/Documentation/BreakingChanges.txt > @@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, > > === Removals > > +* 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. "reositories" -> "repositories". > + ** 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>. > + > == Superseded features that will not be deprecated > > Some features have gained newer replacements that aim to improve the design in ``` ## Junio C Hamano, 2024-06-04 18:01 Subject: Re: [PATCH v6 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqjzj4vb7y.fsf%40gitster.g In-Reply-To: ``` Phillip Wood writes: > Hi Patrick > > On 04/06/2024 13:32, Patrick Steinhardt wrote: >> 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. > > This version looks good to me > > Thanks for writing this document Yup, aside from two typos and a misstatement I did not spot anything that need correction. Will queue. Thanks. ``` ## Patrick Steinhardt, 2024-06-05 05:31 Subject: Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/Zl_4IIqFmoPhx1Gc%40tanuki In-Reply-To: ``` On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote: > Patrick Steinhardt 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, 2024-06-05 05:32 Subject: Re: [PATCH v6 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/Zl_4dDkmj8sJegrp%40tanuki In-Reply-To: ``` On Tue, Jun 04, 2024 at 11:01:21AM -0700, Junio C Hamano wrote: > Phillip Wood writes: > > > Hi Patrick > > > > On 04/06/2024 13:32, Patrick Steinhardt wrote: > >> 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. > > > > This version looks good to me > > > > Thanks for writing this document > > Yup, aside from two typos and a misstatement I did not spot anything > that need correction. Will queue. > > Thanks. Thanks to both of you! Patrick ``` ## Junio C Hamano, 2024-06-05 16:03 Subject: Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqjzj3wf4m.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: > On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote: >> Patrick Steinhardt 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, 2024-06-05 17:52 Subject: Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqqplsvs2et.fsf%40gitster.g In-Reply-To: ``` Junio C Hamano 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 . release numbers these days, starting from Git +2.0, for feature releases, our plan is to increment in the +release number when we make the next breaking release (before Git 2.0, +the release numbers were 1.. with the intention to increment + 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 ``` ## Patrick Steinhardt, 2024-06-06 04:35 Subject: Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/ZmE8myG5c99UJeCA%40tanuki In-Reply-To: ``` On Wed, Jun 05, 2024 at 10:52:10AM -0700, Junio C Hamano wrote: > Junio C Hamano 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 ``` ## Patrick Steinhardt, 2024-06-14 06:42 Subject: [PATCH v7 0/4] docs: document upcoming breaking changes Message-ID: URL: https://gitlist.dev/e/cover.1718345026.git.ps%40pks.im In-Reply-To: ``` 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 . release numbers these days, starting from Git 2.0. For ++future releases, our plan is to increment in the release number when we ++make the next breaking release. Before Git 2.0, the release numbers were ++1.. with the intention to increment 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 -- 2.45.2.457.g8d94cfb545.dirty ``` ## Patrick Steinhardt, 2024-06-14 06:42 Subject: [PATCH v7 1/4] docs: introduce document to announce breaking changes Message-ID: <6348f27b591f306d79c69594ed3157e22ac4774c.1718345026.git.ps@pks.im> URL: https://gitlist.dev/e/6348f27b591f306d79c69594ed3157e22ac4774c.1718345026.git.ps%40pks.im In-Reply-To: ``` 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 --- Documentation/BreakingChanges.txt | 80 +++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 Documentation/BreakingChanges.txt diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt new file mode 100644 index 0000000000..cb7e30312f --- /dev/null +++ b/Documentation/BreakingChanges.txt @@ -0,0 +1,80 @@ += 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. We had the following +major breaking releases in the past: + +* Git 1.6.0, released in August 2008. +* Git 2.0, released in May 2014. + +We use . release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.. with the intention to increment 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 +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. -- 2.45.2.457.g8d94cfb545.dirty ``` ## Patrick Steinhardt, 2024-06-14 06:42 Subject: [PATCH v7 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Message-ID: URL: https://gitlist.dev/e/d0ec38a25ab4fbdcb8ffa726931ead3fc68662b4.1718345026.git.ps%40pks.im In-Reply-To: ``` Starting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely. Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0. All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index cb7e30312f..68ad42d805 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -70,6 +70,36 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +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>, +. + === Removals == Superseded features that will not be deprecated -- 2.45.2.457.g8d94cfb545.dirty ``` ## Patrick Steinhardt, 2024-06-14 06:42 Subject: [PATCH v7 3/4] BreakingChanges: document removal of grafting Message-ID: URL: https://gitlist.dev/e/deee0bbf667892141b2c79567d946521517fe943.1718345026.git.ps%40pks.im In-Reply-To: ``` The grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs. Follow through with the deprecation and mark grafts for removal in Git 3.0. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 68ad42d805..62695ec2e1 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -102,6 +102,19 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, === Removals +* 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 + repositories. + ** 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>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in -- 2.45.2.457.g8d94cfb545.dirty ``` ## Patrick Steinhardt, 2024-06-14 06:42 Subject: [PATCH v7 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Message-ID: <25b20bb0ca84e6c97d27688f5e7a5f28c7ad5d1b.1718345026.git.ps@pks.im> URL: https://gitlist.dev/e/25b20bb0ca84e6c97d27688f5e7a5f28c7ad5d1b.1718345026.git.ps%40pks.im In-Reply-To: ``` The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions. This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt --- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 62695ec2e1..ba86c0224d 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -121,3 +121,15 @@ 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. + +* 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. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. -- 2.45.2.457.g8d94cfb545.dirty ``` ## Junio C Hamano, 2024-06-14 16:08 Subject: Re: [PATCH v7 1/4] docs: introduce document to announce breaking changes Message-ID: URL: https://gitlist.dev/e/xmqq1q4zik2m.fsf%40gitster.g In-Reply-To: <6348f27b591f306d79c69594ed3157e22ac4774c.1718345026.git.ps@pks.im> ``` Patrick Steinhardt writes: > +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. Sorry if I typofixed silently and locally without mentioning in my reviews for the earlier cycles, but I noticed that the fix "concensus" -> "consensus" I had in 'seen' is gone from this version. I'll locally amend. Thanks. ```