[RFC PATCH] docs: document upcoming breaking changes

[RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 5441 bytes --]

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

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.
-- 
2.45.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Johannes Schindelin]

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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

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.

Re: [RFC PATCH] docs: document upcoming breaking changes

[Phillip Wood]

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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2635 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3762 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3055 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

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?

Re: [RFC PATCH] docs: document upcoming breaking changes

[Dragan Simic]

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/

Re: [RFC PATCH] docs: document upcoming breaking changes

[Justin Tobler]

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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

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.

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 850 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Dragan Simic]

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.

[RFC PATCH v2] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 15437 bytes --]

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 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. <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.
    @@ 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-<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.
    ++
    ++## 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>.

 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. <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.
+
+## 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>.
-- 
2.45.GIT


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2339 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 4948 bytes --]

Patrick Steinhardt <ps@pks.im> 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-<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.

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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4867 bytes --]

On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote:
> Patrick Steinhardt <ps@pks.im> 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 <ref>`.
  $ 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Dragan Simic]

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.

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> 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.

[PATCH v3] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 8905 bytes --]

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

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>.

base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f
-- 
2.45.1.246.gb9cfe4845c.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] docs: document upcoming breaking changes

[Junio C Hamano]

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.