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

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

Ævar Arnfjörð Bjarmason  [off-list ref] writes:

quoted

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.