From: Patrick Steinhardt <ps@pks.im>
Date: Tue, 23 Sep 2025 08:03:31 GMT
Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES
Message-ID: <aNJUUxfhM7QYDQGj@pks.im>
In-Reply-To: <xmqqjz1u161e.fsf@gitster.g>

On Fri, Sep 19, 2025 at 02:33:33PM -0700, Junio C Hamano wrote:
> Shouldn't we do something like this for breaking builds?
> 
> Documentation/Makefile pays attention to EXCLUDED_PROGRAMS to
> pretend that the git-$deprecated.adoc files do not exist
> 
>     -include GIT-EXCLUDED-PROGRAMS
> 
>     MAN1_TXT += $(filter-out \
>                     $(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \
>                     $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \
>                     $(wildcard git-*.adoc))
> 
> but nobody seems to put the removed programs on the list.  
> 
> The dependencies around Documentation/GIT-EXCLUDED-PROGRAMS is still
> screwed up, I think, but this may be a good first step to straighten
> it out.  If "make -C Documentation" runs lint-docs by default, for
> example, we may want to tweak the Makefile down there to make
> link-docs target depend on the GIT-EXCLUDED-PROGRAMS perhaps.
> 
> diff --git i/Makefile w/Makefile
> index 893070be76..711cade8fd 100644
> --- i/Makefile
> +++ w/Makefile

Curious, but what's up with the "i" and "w" prefixes here? :)

> @@ -892,6 +892,8 @@ BUILT_INS += git-switch$X
>  BUILT_INS += git-version$X
>  ifndef WITH_BREAKING_CHANGES
>  BUILT_INS += git-whatchanged$X
> +else
> +EXCLUDED_PROGRAMS += git-whatchanged
>  endif
>  
>  # what 'all' will build but not install in gitexecdir

I think this change makes sense indeed. It means that we stop linting
the docs, which is a bit of a weird side effect that may or may not be
sensible. But in any case, we should probably stop installing these man
pages.

I say "probably" because this got me thinking: we could keep the man
page for a while, but completely replace their its with a notice saying
that the command got removed. Even better, we could even tell users what
the replacement is.

Patrick