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

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

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