Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 23, 2025, 14:43 UTC
Message-ID: <xmqqikh9p6ub.fsf@gitster.g>
In-Reply-To: <aNJUUxfhM7QYDQGj@pks.im>

Patrick Steinhardt <ps@pks.im> writes:

Show 6 quoted lines

>> 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? :)

They indicate that you are looking at uncommitted "here is what I typed in the working tree for illustration" changes ;-).

Show 9 quoted lines

> 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.

Thanks.