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

[Patrick Steinhardt <ps@pks.im>]

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

On Fri, May 24, 2024 at 10:27:13AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > case, most of the proposed deprecations didn't get much pushback. I'm
> > less sure whether this is because people didn't look, or because they
> > silently agree with what I propose for deprecation.
> 
> Or because I explicitly said that first we'll brainstorm, in order
> to encourage generation of more ideas, without shooting other
> people's ideas down?

Fair, I guess.

[snip]
> > +## Git 3.0
> 
> Question.  
> 
> Will we have "## Git 4.0" etc., to indicate the timelines (some
> stuff we might eventually replace/change, but we may not ready yet
> by the time 3.0 comes)?  Or do we assme that an idea we agree enough
> on to add to this document would all be ready to be implemented by
> 3.0?

Good question. For now I have added such items to the "Superseded
features that will not be deprecated" section, with a hint that we may
revisit the deprecation in the future. E.g. for the git-config(1)
actions I say the following:

    The action flags will not be removed in the next major Git release
    as there likely exist a lot of scripts out there that use the old
    syntax.

I think that this is easiest to manage for other features where we are
not yet ready to commit to a deprecation, as well, due to whatever
reason. Those items can be added along with a condition that, once met,
may prompt us to revisit a deprecation.

> > +### Changes
> > +
> > +  - The default initial branch name will be changed from "master" to "main".
> > +
> > +    Cf. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
> > +    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
> 
> Forcing readers to read entire threads for these two discussions
> somehow feels brutal at least to me.  And reading only these two
> individual messages does not give readers much insight.
> 
> Saying "this was discussed in the past in late 2020, and because
> major hosting sites give 'main' as the initial branch by default for
> new users unless configured these days, we will match to avoid end
> user confusion", if we want to explain why we are changing it,
> should be sufficient.  But seeing that the other two items below do
> not have any such explanation, we may be better of not having it
> here, perhaps?
> 
> I take this iteration to illustrate the format of items (and what
> kinds of items) we want to have in the document.  If the proposal
> made by the above item is:
> 
>     Once we have a discussion thread that shows clear concensus
>     (neither of the above two are not), we'd record the decision and
>     have a reference to the thread.
> 
> then I 100% agree with the plan for this document.

Yes, that's my intent. The bullet item should be self-explaining,
potentially with one or two sentences explaining why. The reference to
the mailing list thread is supposed to give a pointer where, when and
why this decision was made so that people can revisit the discussion.

So the two bullet points below are certainly quite lazy because they do
not provide any context whatsoever.

> > +  - The default hash function for new repositories will be changed from "sha1"
> > +    to "sha256".
> > +
> > +  - The default ref backend for new repositories will be changed from "files" to
> > +    "reftable".
> > +
> > +### Removals
> > +
> > + - git-http-push(1) can be used to push objects to a remote repository via
> > +   HTTP/DAV. Support for write support via WebDAV is not in widespread use
> > +   nowadays anymore and will be removed together with the command.
> > +
> > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP
> > +   server like Apache. The protocol has not seen any updates recently and is
> > +   neither compatible with alternative hash functions nor with alternative ref
> > +   backends. It will thus be removed.
> > +
> > + - git-update-server-info(1) generates data required when serving data via the
> > +   dumb HTTP protocol. Given the removal of that protocol, it serves no purpose
> > +   anymore and will be removed together with the protocol. This includes the
> > +   "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the
> > +   `git repack -n` flag.
> > +
> > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify
> > +   shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This
> > +   concept has long been replaced by remotes and will thus be removed.
> 
> "remotes" -> "the 'remotes.*.*' configuration variables", perhaps?
> 
> > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
> > +   HTTP server. These scripts have been unmaintained for a significant amount of
> > +   time and will be removed.
> 
> Do we want to give plausible alternatives (or merely hinting
> existence of alternatives might be sufficient)?

I guess that would be solutions like cgit, right? While those
recommendations may go stale over time, I still think it'd be worthwhile
to help our users in case they do rely on any deprecated feature.

> > + - git-filter-branch(1) can be used to rewrite history of a repository. It is
> > +   very slow, hard to use and has many gotchas. It will thus be removed in favor
> > +   of [git-filter-repo](https://github.com/newren/git-filter-repo).
> > +
> > + - The "dashed form", i.e. support for calling `git-<command>` instead of
> > +   `git <command>` in scripts, has been deprecated for a long time and will be
> > +   removed.
> 
> I find this questionable but as you said, we'll start from skeletal
> form of this document (without any items), have discussion thread on
> each of these items, and add back those we have concensus on, so
> I'll not further talk about this item in this message.

I'd propose to have one (hopefully uncontroversial) item per section
just to demonstrate how the format is supposed to look like. But other
than that I'm happy to drop most of these items.

> > + - The command to import patches from Quilt seems to be used rarely, if
> > +   ever, and will be removed.
> 
> Not limited to this item, but do we want to mention in this document
> how we measured the actual usage, which we base our deprecation
> decision on?  I do not think such a comment should be attached to
> each of these items (this one and the next one are proposed for the
> same reason),...
> 
> > + - Support for importing repositories from GNU Arch will be removed because
> > +   it would not appear to have any users.
> 
> ... but in a preamble of the document, e.g., "methodology and
> criteria we used to propose these removals".  Random ideas that may
> or may not work:
> 
>  - debian popcon?
>  - google trends, counting the appearance of queries?
>  - telemetry from commands that call home (we do not have any)?

That would certainly be helpful to give us a better base to argue.

> > + - git-config(1) has learned to use subcommands that replace implicit actions
> > +   (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config
> > +   --unset-all`). The action flags will not be removed in the next major Git
> > +   release as there likely exist a lot of scripts out there that use the old
> > +   syntax.
> > +
> > +   Cf. <ZjiL7vu5kCVwpsLd@tanuki>.
> 
> This is a good example of "we had a concensus back when this was
> discussed; see the thread this message is on".  I think it would be
> beneficial to write down what these references _mean_ at the beginning
> of the document, e.g.
> 
>     When this document refers to a message-ID, you can visit
> 
>       https://lore.kernel.org/git/$message_id/
> 
>     to see the message and its surrounding discussion.  Such a
>     reference is there to make it easier for you to find that the
>     project reached concensus on the described item back then.  As
>     this is a living document, and the environment surrounding the
>     project changes over time, an earlier decision to deprecate or
>     change something may need to be revisited from time to time, so
>     do not take these references to mean "it is settled, do not
>     waste our time bringing it up again".
> 
> or something like that.

Good idea, will do.

Patrick

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