# [RFC] doc: check-docs and WITH_BREAKING_CHANGES 6 messages from 2025-09-19 to 2025-09-23. Participants: Junio C Hamano, Patrick Steinhardt, Ben Knoble. Thread: https://gitlist.dev/t/64172 ## Junio C Hamano, 2025-09-19 21:33 Subject: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/xmqqjz1u161e.fsf%40gitster.g ``` 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, 2025-09-23 08:03 Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/aNJUUxfhM7QYDQGj%40pks.im In-Reply-To: ``` 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 ``` ## Ben Knoble, 2025-09-23 13:30 Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/DD6B592F-005D-4F36-9585-003C1C4ADAE5%40gmail.com In-Reply-To: ``` > Le 23 sept. 2025 à 04:03, Patrick Steinhardt 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, 2025-09-23 13:58 Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/aNKnmxtcrWH_GlAV%40pks.im In-Reply-To: ``` On Tue, Sep 23, 2025 at 09:30:28AM -0400, Ben Knoble wrote: > > > Le 23 sept. 2025 à 04:03, Patrick Steinhardt 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, 2025-09-23 14:43 Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/xmqqikh9p6ub.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt writes: >> 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 ;-). > 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, 2025-09-23 14:50 Subject: Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES Message-ID: URL: https://gitlist.dev/e/aNKzp598Wr0Ut8yC%40pks.im In-Reply-To: ``` On Tue, Sep 23, 2025 at 07:43:40AM -0700, Junio C Hamano wrote: > Patrick Steinhardt 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 ```