Subject: Re: [PATCH] Documentation/Makefile: don't re-build on 'git version' changes

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Sat, 03 Jul 2021 13:58:55 +0200

On Fri, Jul 02 2021, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <[email-masked]> writes:
>
>> Since 9a71722b4df (Doc: auto-detect changed build flags, 2019-03-17)
>> we've been eagerly re-building the documentation whenever the output
>> of "git version" (via the GIT-VERSION file) changed. This was never
>> the intention, and was a regression on what we intended in
>> 7b8a74f39cb (Documentation: Replace @@GIT_VERSION@@ in documentation,
>> 2007-03-25).
>
> I am not sure.  Even if there were no changes in say
> 'Documentation/git-cat-file.txt' and the sources it depends on
> between 'master' and 'next', after doing this:
>
>     $ git checkout next
>     $ make prefix=$HOME/git-next/ install install-doc
>     $ git checkout master
>     $ make prefix=$HOME/git-master/ install install-doc
>     $ $HOME/git-master/bin/git help cat-file | tail -n 1
>
> I should see that the documentation should say it is from the
> 'master' branch in its footer, no?

Yes in theory, in practice it's very annoying to have the very slow
documentation build be re-built so aggressively. Since it wasn't a
practical issue anyone worried about before 2019 I think it's worth
reverting it.

> In other words, I think 7b8a74f39cb's reasoning (not the
> implementation), especially the last sentence of its log message, is
> flawed, where it said:
>
>     Documentation: Replace @@GIT_VERSION@@ in documentation
>     
>     Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in
>     the HTML and XML asciidoc output. The documentation
>     doesn't depend on GIT-VERSION-FILE so it will not be
>     automatically rebuild if nothing else changed.

Arguably it's a feature. The point of the version in the documentation
is to make it clear what version we're discussing. If I build something
on the master SHA-1 and advance to next, and none of the documentation
dependencies change, it's most useful to refer to the oldest last
version we can cover.

I think nobody's doing such a "chained" build when building the docs for
a "real" release, and having mixed versions might be confusing, but for
the "local build" case from a development checkout it's arguably more
useful.