[RFC] doc: check-docs and WITH_BREAKING_CHANGES

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 19, 2025, 21:33 UTC
Message-ID: <xmqqjz1u161e.fsf@gitster.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