| Message ID | 84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> 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. <pull.762.git.1605221038.gitgitgadget@gmail.com>, > + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>. 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-<command>` instead of > + `git <command>` 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. <ZjiL7vu5kCVwpsLd@tanuki>. 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.
Kevin Day <toasty@dragondata.com> writes: >>> 1) Fix -h handling and add ignores and fixes where possible to the >>> failing tests and try to not use -h as an option for anything new. >> >> I do not quite understand the former half, but "try not to use -h >> for new things" is a very good idea and it is pretty much what we >> have been doing. > > Sorry, let me rephrase that. 1) Apply the fix I was proposing to make > it so that the command's -h usage has precedence over showing the > usage. Any tests that break because of that which don't have a > plausible fix mark as "# TODO known breakage" like several other > commands have because they aren't generating usage output correctly > for one reason or another. Ah, then no. I am afraid that it is a non starter. "git ls-remote -h" would then stop breaking existing users' long established expectation, i.e., "for any git subcommand 'cmd', you can say 'git cmd -h' to get the short help". We need to design a good transition plan to wean existing users off of that expectation. For example, we _could_ introduce "-?" to parse-options _now_, and mark the use of "-h" as deprecated. When the special casing of "-h" parse-options has triggers, the user will be reminded that the "-h" support will have a limited shelf life, and they are urged to retrain their fingers and update their scripts to use "-?", possibly with "advice.shorthelpdeprecationnotice" configuration knob that helps ease the transition. We would update the t/ scripts to use "-?" at the same time, but would probably need to keep tests that use "-h" to ensure that the warning triggers. We will keep things that way for a while, and once we get the users' expectation updated so that they think 'git cmd -?' (not 'git cmd -h') is _the_ way to get the short help for any git subcommand. At a major version boundary, e.g., Git 3.0, we could remove the special casing of '-h' from parse-options, and "git ls-remote -h" will start working the same way as "git ls-remote -h origin" all of a sudden, but nobody remembers "git ls-remote -h" used to be the way to get short help for the command any more by that time, so nobody will get hurt by such a flipping of the behaviour.
On Fri, May 24, 2024 at 10:27:13AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> 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. <pull.762.git.1605221038.gitgitgadget@gmail.com>, > > + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>. > > 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-<command>` instead of > > + `git <command>` 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. <ZjiL7vu5kCVwpsLd@tanuki>. > > 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
Junio C Hamano <gitster@pobox.com> writes: > Ah, then no. > > I am afraid that it is a non starter. "git ls-remote -h" would then > start breaking existing users' long established expectation, i.e., > "for any git subcommand 'cmd', you can say 'git cmd -h' to get the > short help". We need to design a good transition plan to wean > existing users off of that expectation. Another thing I forgot to mention. For "ls-remote" and "show-ref", there is a much nicer transition path we can take. Back in Linus's days, we called branches "heads" (and we used $GIT_DIR/refs/heads/ to store them as individual files), but if we were starting Git from scratch today, there is no reason to. Call branches branches, not heads, which means we do not need to use "-h" to mean "I want to see only the branches and no other refs" at all. You say "--branches" instead. Which leads to an obvious transition path, which is * Introduce "--branches" that sits next to "--tags" to "ls-remote" and "show-ref". If the command has "-t" as a short-hand for "--tags", then add "-b" as a short-hand for "--branches". Announce that "--heads" (and "-h" if supported) is deprecated for these commands, and when "--heads" (and "-h" if supported) is used, give a warning to train finger/muscle memory early. * We will keep things that way for a while, and then remove the "--heads" (and "-h" if supported) from these two commands. The approach cannot be used to transition "git grep -h" for obvious reasons, but then it makes no sense to give "-h" alone to tell the command "I do not want to see filenames", so that is not a problem. I checked output from $ git grep -A2 '^-h' Documentation/ and it seems that ls-remote is the only one that matters, so we do not even have to do the "-?" transition at all. Thanks.
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. <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-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-<command>` instead of + `git <command>` 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. <ZjiL7vu5kCVwpsLd@tanuki>.
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 <ps@pks.im> --- 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 base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f