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

From: Patrick Steinhardt <[email-masked]>
Date: Wed, 8 May 2024 15:55:10 +0200

On Wed, May 08, 2024 at 02:15:11PM +0100, Phillip Wood wrote:
> Hi Patrick
> 
> Thanks putting this together, I think it will be a useful way discussing
> deprecations and removals.
> 
> On 07/05/2024 09:27, 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.
> 
> Is the plan to use this document to track the progress/status of proposed
> deprecations? For example the config based hooks implementation is stalled
> at the moment and would need some work before we can remove $GIT_DIR/hooks

I also have it in my backlog to propose a file that may keep a record of
long-running projects. The intent would be similar to this patch here,
but it should also help newcomers to find projects to work on.

This would track:

  - Large-scale efforts like the past SHA256 migration or removal of
    `the_repository`.

  - Small projects or microprojects like we have in GSoC to help out
    newcomers when they want to work on stuff.

  - Things we have already discussed, but simply didn't get landed yet
    like the hooks refactoring.

So agreed, the hook refactorings should not be part of the deprecations
document when it hasn't even landed yet.

> > +### 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.
> 
> I agree we want to allow plenty of time for script authors to migrate their
> scripts here.
> 
> > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has
> > +   been a source of multiple remote code execution vulnerabilities.
> 
> I'm not sure about the reasoning here as a hook has to be enabled by the
> user before it is run. There are good reasons to prefer config based hooks
> such as the ability to run multiple scripts per hook event but I don't think
> they are inherently more secure.

I'll remove this item for now. We can discuss it again when (if) the
config based mechanisms land.

Patrick