| Message ID | fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [RFC] docs: document upcoming breaking changes | expand |
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 <ps@pks.im> > --- > > 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. <pull.762.git.1605221038.gitgitgadget@gmail.com>, > + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>. > + > + - 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. <ZjiL7vu5kCVwpsLd@tanuki>. > + > + - 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-<command>` instead of `git <command>` 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
Patrick Steinhardt <ps@pks.im> writes: > Over time, Git has grown quite a lot. With this evolution, many ideas > that were sensible at the time they were introduced are not anymore and > are thus considered to be deprecated. And while some deprecations may be > noted in manpages, most of them are actually deprecated in the "hive > mind" of the Git community, only. 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.
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
On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > > > Over time, Git has grown quite a lot. With this evolution, many ideas > > that were sensible at the time they were introduced are not anymore and > > are thus considered to be deprecated. And while some deprecations may be > > noted in manpages, most of them are actually deprecated in the "hive > > mind" of the Git community, only. > > 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
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-<command>` instead of > `git <command>` 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
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
Patrick Steinhardt <ps@pks.im> 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?
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/
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. <ZjiL7vu5kCVwpsLd@tanuki>. > + > + - 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
Justin Tobler <jltobler@gmail.com> 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.
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
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.
On Thu, May 09, 2024 at 09:47:49PM -0700, Junio C Hamano wrote: > Justin Tobler <jltobler@gmail.com> 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
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. <pull.762.git.1605221038.gitgitgadget@gmail.com>, + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>. + + - 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. <ZjiL7vu5kCVwpsLd@tanuki>. + + - 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.
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 <ps@pks.im> --- 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