[RFC PATCH] docs: document upcoming breaking changes

From: Patrick Steinhardt <ps@pks.im>
Date: May 7, 2024, 08:27 UTC
Message-ID: <fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im>

Over time, Git has grown quite a lot. With this evolution, many ideas that were sensible at the time they were introduced are not anymore and are thus considered to be deprecated. And while some deprecations may be noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only.

Introduce a new document that lists upcoming breaking changes to address this issue. This document serves multiple purposes:

  - It is a way to facilitate discussion around proposed deprecations.

  - It allows users to learn about deprecations and speak up in case
    they have good reasons why a certain feature should not be
    deprecated.

  - It states intent and documents where the Git project wants to go.

The document is _not_ intended to cast every single discussion into stone. It is supposed to be a living document that may change over time when there are good reasons for it to change.

Signed-off-by: Patrick Steinhardt <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