Re: [PATCH] Documentation/Makefile: don't re-build on 'git version' changes
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Jul 3, 2021, 11:58 UTC
- Message-ID
- <87pmvz8v1u.fsf@evledraar.gmail.com>
- In-Reply-To
- <xmqqmtr4pv9r.fsf@gitster.g>
On Fri, Jul 02 2021, Junio C Hamano wrote:
Show 21 quoted lines
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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.
Show 10 quoted lines
> 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.