From: Patrick Steinhardt <ps@pks.im>
Date: Tue, 23 Sep 2025 14:50:15 GMT
Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES
Message-ID: <aNKzp598Wr0Ut8yC@pks.im>
In-Reply-To: <xmqqikh9p6ub.fsf@gitster.g>

On Tue, Sep 23, 2025 at 07:43:40AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > 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.
> 
> That is true but requires a much larger change.
> 
> There is an assumption that programs whose binaries we are not
> installing should not get manual pages, which is what allows us to
> throw git-http-fetch and git-whatchanged to EXCLUDED_PROGRAMS and
> cause (1) them from getting built and installed, and (2) cause their
> manual pages not built and not installed, and (3) tell doc-lint that
> it is OK to have .adoc for these programs' documentation, even
> though they are not listed in the command-list.txt file.  You'd need
> to start from disentangling that.

Fair. I'm completely fine with doing this one step at a time, where the
first step would be to not install manpages that don't make any sense
anymore. Let's see, maybe someone wants to pick up what I propose.

Patrick