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

[Patrick Steinhardt <ps@pks.im>]

[-- 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 --]