threads / rfc / 64172

[RFC] doc: check-docs and WITH_BREAKING_CHANGES

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

## tl;dr

6 messages between Sep 19, 2025 and Sep 23, 2025.

replies: 5people: 3as markdown or json

Junio C Hamano· Sep 19, 2025, 21:33 UTC · lore

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
@@ -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
@@ -1363,6 +1365,8 @@ BUILTIN_OBJS += builtin/notes.o
 BUILTIN_OBJS += builtin/pack-objects.o
 ifndef WITH_BREAKING_CHANGES
 BUILTIN_OBJS += builtin/pack-redundant.o
+else
+EXCLUDED_PROGRAMS += git-pack-redundant
 endif
 BUILTIN_OBJS += builtin/pack-refs.o
 BUILTIN_OBJS += builtin/patch-id.o
@@ -3875,7 +3879,7 @@ ALL_COMMANDS += gitweb
 ALL_COMMANDS += scalar
 
 .PHONY: check-docs
-check-docs::
+check-docs:: Documentation/GIT-EXCLUDED-PROGRAMS
 	$(MAKE) -C Documentation lint-docs
 
 ### Make sure built-ins do not have dups and listed in git.c

Patrick Steinhardt· Sep 23, 2025, 08:03 UTC · re: Junio C Hamano · lore

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

On Fri, Sep 19, 2025 at 02:33:33PM -0700, Junio C Hamano wrote:

Show 24 quoted lines

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

Show 9 quoted lines

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

Ben Knoble· Sep 23, 2025, 13:30 UTC · re: Patrick Steinhardt · lore

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

Show 29 quoted lines

> Le 23 sept. 2025 à 04:03, Patrick Steinhardt <ps@pks.im> a écrit :
> 
> 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? :)

That’s « index » and « working tree » from diff.mnemonicPrefix

Patrick Steinhardt· Sep 23, 2025, 13:58 UTC · re: Ben Knoble · lore

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

On Tue, Sep 23, 2025 at 09:30:28AM -0400, Ben Knoble wrote:

Show 32 quoted lines

> 
> > Le 23 sept. 2025 à 04:03, Patrick Steinhardt <ps@pks.im> a écrit :
> > 
> > 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? :)
> 
> That’s « index » and « working tree » from diff.mnemonicPrefix

Interesting. It's amazing how there's always something new to learn about Git :) Thanks!

Patrick

Junio C Hamano· Sep 23, 2025, 14:43 UTC · re: Patrick Steinhardt · lore

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

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.

Patrick Steinhardt· Sep 23, 2025, 14:50 UTC · re: Junio C Hamano · lore

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

On Tue, Sep 23, 2025 at 07:43:40AM -0700, Junio C Hamano wrote:

Show 21 quoted lines

> 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