Re: implement a stable 'Last updated' in Documentation

[Junio C Hamano <gitster@pobox.com>]

Olaf Hering <olaf@aepfle.de> writes:

> Several files in Documentation have an unstable 'Last updated' timestamp. The
> reason is that their mtime changes every time, which prevents reproducible
> builds.
>
> 341 technical/api-index.txt: technical/api-index-skel.txt \
> 342         technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
> 343         $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
>
> 388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
> 389         $(QUIET_GEN)$(RM) $@+ $@ && \
> 390         '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \
> 391         mv $@+ $@
>
> 399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
> 400         $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> 401         sed -e '1,/^$$/d' $< | \
> 402         $(TXT_TO_HTML) - >$@+ && \
> 403         mv $@+ $@

All of them seem to have dependencies so it seems to me that two
builds back to back without actually changing their input would not
re-build anything.  What am I missing???

> What file timestamp should be used for them? Likely "../version"?

I tend to think the "Last updated" timestamp taken from the
filesystem timestamp is a bad practice inherited by these tools from
the days back when nobody used any revision control systems.

If I check out v1.8.5 and build documentation now, it does not
matter if the generated documentation had the timestamp of the
checkout of individual files or that of a single file generated
during the build process, i.e. ../version.  Neither has much
relevance to the time the actual contents of the documentation was
prepared or what vintage of the software the documentation is for.

I am fine with branding generated documentation with the version
number (i.e. "You are reading the documentation for Git version
2.2.0").  Replacing that statement with "You are reading the
documentation for a version of Git that was committed on such and
such time" is also fine.  But using file timestamp would not help
either.

And that practice of using file timestamp is doubly bad by leading
misguided people to want to set timestamps of all the files by
copying commit timestamp.  That is backwards, I would think.