[PATCH] Documentation/Makefile: fix lint-docs mkdir dependency

Since 8650c6298c (doc lint: make "lint-docs" non-.PHONY, 2021-10-15), we
put the output for gitlink linter into .build/lint-docs/gitlink. There
are order-only dependencies to create the sequence of subdirs like:

  .build/lint-docs: | .build
          $(QUIET)mkdir $@
  .build/lint-docs/gitlink: | .build/lint-docs
          $(QUIET)mkdir $@

where each level has to depend on the prior one (since the parent
directory must exist for us to create something inside it). But the
"howto" and "config" subdirectories of gitlink have the wrong
dependency; they depend on "lint-docs", not "lint-docs/gitlink".

This usually works out, because the LINT_DOCS_GITLINK targets which
depend on "gitlink/howto" also depend on just "gitlink", so the
directory gets created anyway. But since we haven't given make an
explicit ordering, things can racily happen out of order.

If you stick a "sleep 1" in the rule to build "gitlink" like this:

   ## Lint: gitlink
   .build/lint-docs/gitlink: | .build/lint-docs
  -	$(QUIET)mkdir $@
  +	$(QUIET)sleep 1 && mkdir $@

then "make clean; make lint-docs" will fail reliably. Or you can see it
as-is just by building the directory in isolation:

  $ make clean
  [...]
  $ make .build/lint-docs/gitlink/howto
      GEN mergetools-list.made
      GEN cmd-list.made
      GEN doc.dep
      SUBDIR ../
  make[1]: 'GIT-VERSION-FILE' is up to date.
      SUBDIR ../
  make[1]: 'GIT-VERSION-FILE' is up to date.
  mkdir: cannot create directory ‘.build/lint-docs/gitlink/howto’: No such file or directory
  make: *** [Makefile:476: .build/lint-docs/gitlink/howto] Error 1

The fix is easy: we just need to depend on the correct parent directory.

Signed-off-by: Jeff King <redacted>
---
The problem starts in ab/fix-make-lint-docs, which is in master.

I wasn't able to trigger the problem locally even with running 'make
clean; make lint-docs' in a loop, but I did see it in the wild in a CI
documentation job:

  https://github.com/peff/git/runs/4005766641?check_suite_focus=true#step:4:60

It would have been a lot easier to diagnose from the CI output if the
mkdir lines weren't silent. I.e., if we had a $(QUIET_MKDIR) which
printed "MKDIR $@" rather than nothing at all.

 Documentation/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 911b6bf79c..ed656db2ae 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -472,9 +472,9 @@ print-man1:
 ## Lint: gitlink
 .build/lint-docs/gitlink: | .build/lint-docs
 	$(QUIET)mkdir $@
-.build/lint-docs/gitlink/howto: | .build/lint-docs
+.build/lint-docs/gitlink/howto: | .build/lint-docs/gitlink
 	$(QUIET)mkdir $@
-.build/lint-docs/gitlink/config: | .build/lint-docs
+.build/lint-docs/gitlink/config: | .build/lint-docs/gitlink
 	$(QUIET)mkdir $@
 LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
 $(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink

-- 
2.33.1.1387.g97d4a0c3a8

On Tue, Oct 26 2021, Jeff King wrote:

Thanks a lot for fixing that bug, and sorry for not spotting it. This
fix LGTM and is obviously correct.

I'll try to do something about the $(QUIET*) as a follow-up, I was
trying to find the right balance between over-verbosity & "tracing".

On Tue, Oct 26, 2021 at 12:05:40PM +0200, Ævar Arnfjörð Bjarmason wrote:

I'll try to do something about the $(QUIET*) as a follow-up, I was
trying to find the right balance between over-verbosity & "tracing".

Yeah, I wondered if it would end up super-verbose. But I tried it out
and IMHO it looks just fine to print mkdir lines. In the initial build,
"make" realizes we only need to run each rule once, and in subsequent
builds it doesn't run them at all.

-Peff