{"thread":{"id":"64172","subject":"[RFC] doc: check-docs and WITH_BREAKING_CHANGES","startedAt":"2025-09-19T21:33:35Z","lastAt":"2025-09-23T14:50:21Z","messageCount":6,"participants":["Junio C Hamano","Patrick Steinhardt","Ben Knoble"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"526822","messageId":"xmqqjz1u161e.fsf@gitster.g","threadId":"64172","inReplyTo":null,"subject":"[RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-19T21:33:33Z","receivedAt":"2025-09-19T21:33:35Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shouldn't we do something like this for breaking builds?\n\nDocumentation/Makefile pays attention to EXCLUDED_PROGRAMS to\npretend that the git-$deprecated.adoc files do not exist\n\n    -include GIT-EXCLUDED-PROGRAMS\n\n    MAN1_TXT += $(filter-out \\\n                    $(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \\\n                    $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \\\n                    $(wildcard git-*.adoc))\n\nbut nobody seems to put the removed programs on the list.  \n\nThe dependencies around Documentation/GIT-EXCLUDED-PROGRAMS is still\nscrewed up, I think, but this may be a good first step to straighten\nit out.  If \"make -C Documentation\" runs lint-docs by default, for\nexample, we may want to tweak the Makefile down there to make\nlink-docs target depend on the GIT-EXCLUDED-PROGRAMS perhaps.\n\ndiff --git i/Makefile w/Makefile\nindex 893070be76..711cade8fd 100644\n--- i/Makefile\n+++ w/Makefile\n@@ -892,6 +892,8 @@ BUILT_INS += git-switch$X\n BUILT_INS += git-version$X\n ifndef WITH_BREAKING_CHANGES\n BUILT_INS += git-whatchanged$X\n+else\n+EXCLUDED_PROGRAMS += git-whatchanged\n endif\n \n # what 'all' will build but not install in gitexecdir\n@@ -1363,6 +1365,8 @@ BUILTIN_OBJS += builtin/notes.o\n BUILTIN_OBJS += builtin/pack-objects.o\n ifndef WITH_BREAKING_CHANGES\n BUILTIN_OBJS += builtin/pack-redundant.o\n+else\n+EXCLUDED_PROGRAMS += git-pack-redundant\n endif\n BUILTIN_OBJS += builtin/pack-refs.o\n BUILTIN_OBJS += builtin/patch-id.o\n@@ -3875,7 +3879,7 @@ ALL_COMMANDS += gitweb\n ALL_COMMANDS += scalar\n \n .PHONY: check-docs\n-check-docs::\n+check-docs:: Documentation/GIT-EXCLUDED-PROGRAMS\n \t$(MAKE) -C Documentation lint-docs\n \n ### Make sure built-ins do not have dups and listed in git.c\n"},{"id":"527027","messageId":"aNJUUxfhM7QYDQGj@pks.im","threadId":"64172","inReplyTo":"xmqqjz1u161e.fsf@gitster.g","subject":"Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-23T08:03:31Z","receivedAt":"2025-09-23T08:03:37Z","isPatch":false,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Sep 19, 2025 at 02:33:33PM -0700, Junio C Hamano wrote:\n> Shouldn't we do something like this for breaking builds?\n> \n> Documentation/Makefile pays attention to EXCLUDED_PROGRAMS to\n> pretend that the git-$deprecated.adoc files do not exist\n> \n>     -include GIT-EXCLUDED-PROGRAMS\n> \n>     MAN1_TXT += $(filter-out \\\n>                     $(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \\\n>                     $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \\\n>                     $(wildcard git-*.adoc))\n> \n> but nobody seems to put the removed programs on the list.  \n> \n> The dependencies around Documentation/GIT-EXCLUDED-PROGRAMS is still\n> screwed up, I think, but this may be a good first step to straighten\n> it out.  If \"make -C Documentation\" runs lint-docs by default, for\n> example, we may want to tweak the Makefile down there to make\n> link-docs target depend on the GIT-EXCLUDED-PROGRAMS perhaps.\n> \n> diff --git i/Makefile w/Makefile\n> index 893070be76..711cade8fd 100644\n> --- i/Makefile\n> +++ w/Makefile\n\nCurious, but what's up with the \"i\" and \"w\" prefixes here? :)\n\n> @@ -892,6 +892,8 @@ BUILT_INS += git-switch$X\n>  BUILT_INS += git-version$X\n>  ifndef WITH_BREAKING_CHANGES\n>  BUILT_INS += git-whatchanged$X\n> +else\n> +EXCLUDED_PROGRAMS += git-whatchanged\n>  endif\n>  \n>  # what 'all' will build but not install in gitexecdir\n\nI think this change makes sense indeed. It means that we stop linting\nthe docs, which is a bit of a weird side effect that may or may not be\nsensible. But in any case, we should probably stop installing these man\npages.\n\nI say \"probably\" because this got me thinking: we could keep the man\npage for a while, but completely replace their its with a notice saying\nthat the command got removed. Even better, we could even tell users what\nthe replacement is.\n\nPatrick\n"},{"id":"527074","messageId":"DD6B592F-005D-4F36-9585-003C1C4ADAE5@gmail.com","threadId":"64172","inReplyTo":"aNJUUxfhM7QYDQGj@pks.im","subject":"Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-23T13:30:28Z","receivedAt":"2025-09-23T13:30:41Z","isPatch":false,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 23 sept. 2025 à 04:03, Patrick Steinhardt <ps@pks.im> a écrit :\n> \n> On Fri, Sep 19, 2025 at 02:33:33PM -0700, Junio C Hamano wrote:\n>> Shouldn't we do something like this for breaking builds?\n>> \n>> Documentation/Makefile pays attention to EXCLUDED_PROGRAMS to\n>> pretend that the git-$deprecated.adoc files do not exist\n>> \n>>    -include GIT-EXCLUDED-PROGRAMS\n>> \n>>    MAN1_TXT += $(filter-out \\\n>>                    $(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \\\n>>                    $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \\\n>>                    $(wildcard git-*.adoc))\n>> \n>> but nobody seems to put the removed programs on the list.  \n>> \n>> The dependencies around Documentation/GIT-EXCLUDED-PROGRAMS is still\n>> screwed up, I think, but this may be a good first step to straighten\n>> it out.  If \"make -C Documentation\" runs lint-docs by default, for\n>> example, we may want to tweak the Makefile down there to make\n>> link-docs target depend on the GIT-EXCLUDED-PROGRAMS perhaps.\n>> \n>> diff --git i/Makefile w/Makefile\n>> index 893070be76..711cade8fd 100644\n>> --- i/Makefile\n>> +++ w/Makefile\n> \n> Curious, but what's up with the \"i\" and \"w\" prefixes here? :)\n\nThat’s « index » and « working tree » from diff.mnemonicPrefix"},{"id":"527075","messageId":"aNKnmxtcrWH_GlAV@pks.im","threadId":"64172","inReplyTo":"DD6B592F-005D-4F36-9585-003C1C4ADAE5@gmail.com","subject":"Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-23T13:58:51Z","receivedAt":"2025-09-23T13:58:58Z","isPatch":false,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Sep 23, 2025 at 09:30:28AM -0400, Ben Knoble wrote:\n> \n> > Le 23 sept. 2025 à 04:03, Patrick Steinhardt <ps@pks.im> a écrit :\n> > \n> > On Fri, Sep 19, 2025 at 02:33:33PM -0700, Junio C Hamano wrote:\n> >> Shouldn't we do something like this for breaking builds?\n> >> \n> >> Documentation/Makefile pays attention to EXCLUDED_PROGRAMS to\n> >> pretend that the git-$deprecated.adoc files do not exist\n> >> \n> >>    -include GIT-EXCLUDED-PROGRAMS\n> >> \n> >>    MAN1_TXT += $(filter-out \\\n> >>                    $(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \\\n> >>                    $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \\\n> >>                    $(wildcard git-*.adoc))\n> >> \n> >> but nobody seems to put the removed programs on the list.  \n> >> \n> >> The dependencies around Documentation/GIT-EXCLUDED-PROGRAMS is still\n> >> screwed up, I think, but this may be a good first step to straighten\n> >> it out.  If \"make -C Documentation\" runs lint-docs by default, for\n> >> example, we may want to tweak the Makefile down there to make\n> >> link-docs target depend on the GIT-EXCLUDED-PROGRAMS perhaps.\n> >> \n> >> diff --git i/Makefile w/Makefile\n> >> index 893070be76..711cade8fd 100644\n> >> --- i/Makefile\n> >> +++ w/Makefile\n> > \n> > Curious, but what's up with the \"i\" and \"w\" prefixes here? :)\n> \n> That’s « index » and « working tree » from diff.mnemonicPrefix\n\nInteresting. It's amazing how there's always something new to learn\nabout Git :) Thanks!\n\nPatrick\n"},{"id":"527081","messageId":"xmqqikh9p6ub.fsf@gitster.g","threadId":"64172","inReplyTo":"aNJUUxfhM7QYDQGj@pks.im","subject":"Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-23T14:43:40Z","receivedAt":"2025-09-23T14:43:43Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n>> diff --git i/Makefile w/Makefile\n>> index 893070be76..711cade8fd 100644\n>> --- i/Makefile\n>> +++ w/Makefile\n>\n> Curious, but what's up with the \"i\" and \"w\" prefixes here? :)\n\nThey indicate that you are looking at uncommitted \"here is what I\ntyped in the working tree for illustration\" changes ;-).\n\n> I think this change makes sense indeed. It means that we stop linting\n> the docs, which is a bit of a weird side effect that may or may not be\n> sensible. But in any case, we should probably stop installing these man\n> pages.\n>\n> I say \"probably\" because this got me thinking: we could keep the man\n> page for a while, but completely replace their its with a notice saying\n> that the command got removed. Even better, we could even tell users what\n> the replacement is.\n\nThat is true but requires a much larger change.\n\nThere is an assumption that programs whose binaries we are not\ninstalling should not get manual pages, which is what allows us to\nthrow git-http-fetch and git-whatchanged to EXCLUDED_PROGRAMS and\ncause (1) them from getting built and installed, and (2) cause their\nmanual pages not built and not installed, and (3) tell doc-lint that\nit is OK to have .adoc for these programs' documentation, even\nthough they are not listed in the command-list.txt file.  You'd need\nto start from disentangling that.\n\nThanks.\n\n"},{"id":"527082","messageId":"aNKzp598Wr0Ut8yC@pks.im","threadId":"64172","inReplyTo":"xmqqikh9p6ub.fsf@gitster.g","subject":"Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-23T14:50:15Z","receivedAt":"2025-09-23T14:50:21Z","isPatch":false,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Sep 23, 2025 at 07:43:40AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> > I think this change makes sense indeed. It means that we stop linting\n> > the docs, which is a bit of a weird side effect that may or may not be\n> > sensible. But in any case, we should probably stop installing these man\n> > pages.\n> >\n> > I say \"probably\" because this got me thinking: we could keep the man\n> > page for a while, but completely replace their its with a notice saying\n> > that the command got removed. Even better, we could even tell users what\n> > the replacement is.\n> \n> That is true but requires a much larger change.\n> \n> There is an assumption that programs whose binaries we are not\n> installing should not get manual pages, which is what allows us to\n> throw git-http-fetch and git-whatchanged to EXCLUDED_PROGRAMS and\n> cause (1) them from getting built and installed, and (2) cause their\n> manual pages not built and not installed, and (3) tell doc-lint that\n> it is OK to have .adoc for these programs' documentation, even\n> though they are not listed in the command-list.txt file.  You'd need\n> to start from disentangling that.\n\nFair. I'm completely fine with doing this one step at a time, where the\nfirst step would be to not install manpages that don't make any sense\nanymore. Let's see, maybe someone wants to pick up what I propose.\n\nPatrick\n"}]}