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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 5, 2021, 19:38 UTC
Message-ID: <xmqqh7h8mtzh.fsf@gitster.g>
In-Reply-To: <87mtr38tvd.fsf@evledraar.gmail.com>

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> It's useful e.g. on my Debian system to see that the "next" Debian
> packaged is 2.31.0.291.g576ba9dcdaf in docs & "git version", arguably
> less so for documentation.

If it is arguable, perhaps make an argument that is more convincing?

What I dislike the most is that in the sample scenario where master and next has the same documentation material to build "git-cat-file.1", the installed result would be different depending on the order of building the documentation, with the change being discussed, i.e.

    $ git checkout master && make prefix=$HOME/git-master install-doc
    $ git checkout next && make prefix=$HOME/git-next install-doc

would make "~/git-next/bin/git help cat-file" to claim the documentation is from the "master" version. Which is not all that bad, given that there wasn't anything that changed the documentation between 'master' and 'next'. But if you swap the installation order, "~/git-master/bin/git help cat-file" would say that the documentation is from a version much newer than 'master', which is not quite acceptable.

I am OK with the approach you hinted to have an option to _hide_ the version string in the generated documentation (hence they lose their dependency on GIT-VERSION-FILE), while keeping the dependency of version.o on GIT-VERSION-FILE, so that something goes wrong in a built binary, the developer can still ask "git version" to identify where the binary came from.

Thanks.