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

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