{"thread":{"id":"38455","subject":"implement a stable 'Last updated' in Documentation","startedAt":"2015-01-26T17:24:09Z","lastAt":"2016-09-01T21:18:04Z","messageCount":11,"participants":["Olaf Hering","Junio C Hamano","Michael J Gruber","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"255297","messageId":"20150126172409.GA15204@aepfle.de","threadId":"38455","inReplyTo":null,"subject":"implement a stable 'Last updated' in Documentation","fromName":"Olaf Hering","fromEmail":"olaf@aepfle.de","sentAt":"2015-01-26T17:24:09Z","receivedAt":"2015-01-26T17:24:09Z","isPatch":false,"sender":{"key":"olaf@aepfle.de","avatar":"https://avatars.githubusercontent.com/u/942324?v=4"},"body":"\nSeveral files in Documentation have an unstable 'Last updated' timestamp. The\nreason is that their mtime changes every time, which prevents reproducible\nbuilds.\n\n341 technical/api-index.txt: technical/api-index-skel.txt \\\n342 technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n343 $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n\n388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n389 $(QUIET_GEN)$(RM) $@+ $@ && \\\n390 '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n391 mv $@+ $@\n\n399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n400 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n401 sed -e '1,/^$$/d' $< | \\\n402 $(TXT_TO_HTML) - >$@+ && \\\n403 mv $@+ $@\n\nWhat file timestamp should be used for them? Likely \"../version\"?\nThe final file, before passing it to asciidoc, should get a fixed timestamp\nwith 'touch -r $reference_file $file'.\n\nOlaf\n"},{"id":"255321","messageId":"20150127111107.GA6517@aepfle.de","threadId":"38455","inReplyTo":"20150126172409.GA15204@aepfle.de","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Olaf Hering","fromEmail":"olaf@aepfle.de","sentAt":"2015-01-27T11:11:07Z","receivedAt":"2015-01-27T11:11:07Z","isPatch":false,"sender":{"key":"olaf@aepfle.de","avatar":"https://avatars.githubusercontent.com/u/942324?v=4"},"body":"On Mon, Jan 26, Olaf Hering wrote:\n\n> Several files in Documentation have an unstable 'Last updated' timestamp. The\n> reason is that their mtime changes every time, which prevents reproducible\n> builds.\n> \n> 341 technical/api-index.txt: technical/api-index-skel.txt \\\n> 342 technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> 343 $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n> \n> 388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n> 389 $(QUIET_GEN)$(RM) $@+ $@ && \\\n> 390 '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n> 391 mv $@+ $@\n> \n> 399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n> 400 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> 401 sed -e '1,/^$$/d' $< | \\\n> 402 $(TXT_TO_HTML) - >$@+ && \\\n> 403 mv $@+ $@\n> \n> What file timestamp should be used for them? Likely \"../version\"?\n> The final file, before passing it to asciidoc, should get a fixed timestamp\n> with 'touch -r $reference_file $file'.\n\nI came up with this change. If anything happens to depend on\nhowto-index.txt and technical/api-index.txt then this part needs rework.\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3e39e28..25ad0bd 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -6,6 +6,7 @@ TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n OBSOLETE_HTML =\n+TIMESTAMP_FILE = ../version\n \n MAN1_TXT += $(filter-out \\\n \t\t$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \\\n@@ -341,6 +342,7 @@ user-manual.xml: user-manual.txt user-manual.conf\n technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n+\ttouch -r '$(TIMESTAMP_FILE)' $@\n \n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf\n@@ -388,6 +390,7 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n \t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n+\ttouch -r '$(TIMESTAMP_FILE)' $@+ && \\\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n@@ -397,9 +400,12 @@ WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\tsed -e '1,/^$$/d' $< | \\\n-\t$(TXT_TO_HTML) - >$@+ && \\\n+\t$(QUIET_ASCIIDOC)$(RM) $@++ $@+ $@ && \\\n+\tsed -e '1,/^$$/d' $< >$@++ && \\\n+\ttouch -r '$(TIMESTAMP_FILE)' $@++ && \\\n+\t$(TXT_TO_HTML) -o $@+ $@++ && \\\n+\t$(RM) $@++ && \\\n+\ttouch $@+ && \\\n \tmv $@+ $@\n \n install-webdoc : html\n\nOlaf\n"},{"id":"255352","messageId":"xmqqd25zkeg7.fsf@gitster.dls.corp.google.com","threadId":"38455","inReplyTo":"20150126172409.GA15204@aepfle.de","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-01-27T23:10:16Z","receivedAt":"2015-01-27T23:10:16Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Olaf Hering writes:\n\n> Several files in Documentation have an unstable 'Last updated' timestamp. The\n> reason is that their mtime changes every time, which prevents reproducible\n> builds.\n>\n> 341 technical/api-index.txt: technical/api-index-skel.txt \\\n> 342 technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> 343 $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n>\n> 388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n> 389 $(QUIET_GEN)$(RM) $@+ $@ && \\\n> 390 '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n> 391 mv $@+ $@\n>\n> 399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n> 400 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> 401 sed -e '1,/^$$/d' $< | \\\n> 402 $(TXT_TO_HTML) - >$@+ && \\\n> 403 mv $@+ $@\n\nAll of them seem to have dependencies so it seems to me that two\nbuilds back to back without actually changing their input would not\nre-build anything. What am I missing???\n\n> What file timestamp should be used for them? Likely \"../version\"?\n\nI tend to think the \"Last updated\" timestamp taken from the\nfilesystem timestamp is a bad practice inherited by these tools from\nthe days back when nobody used any revision control systems.\n\nIf I check out v1.8.5 and build documentation now, it does not\nmatter if the generated documentation had the timestamp of the\ncheckout of individual files or that of a single file generated\nduring the build process, i.e. ../version. Neither has much\nrelevance to the time the actual contents of the documentation was\nprepared or what vintage of the software the documentation is for.\n\nI am fine with branding generated documentation with the version\nnumber (i.e. \"You are reading the documentation for Git version\n2.2.0\"). Replacing that statement with \"You are reading the\ndocumentation for a version of Git that was committed on such and\nsuch time\" is also fine. But using file timestamp would not help\neither.\n\nAnd that practice of using file timestamp is doubly bad by leading\nmisguided people to want to set timestamps of all the files by\ncopying commit timestamp. That is backwards, I would think.\n"},{"id":"255389","messageId":"20150128080214.GA18851@aepfle.de","threadId":"38455","inReplyTo":"xmqqd25zkeg7.fsf@gitster.dls.corp.google.com","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Olaf Hering","fromEmail":"olaf@aepfle.de","sentAt":"2015-01-28T08:02:14Z","receivedAt":"2015-01-28T08:02:14Z","isPatch":false,"sender":{"key":"olaf@aepfle.de","avatar":"https://avatars.githubusercontent.com/u/942324?v=4"},"body":"On Tue, Jan 27, Junio C Hamano wrote:\n\n> Olaf Hering writes:\n> \n> > Several files in Documentation have an unstable 'Last updated' timestamp. The\n> > reason is that their mtime changes every time, which prevents reproducible\n> > builds.\n> >\n> > 341 technical/api-index.txt: technical/api-index-skel.txt \\\n> > 342 technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> > 343 $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n> >\n> > 388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n> > 389 $(QUIET_GEN)$(RM) $@+ $@ && \\\n> > 390 '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n> > 391 mv $@+ $@\n> >\n> > 399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n> > 400 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> > 401 sed -e '1,/^$$/d' $< | \\\n> > 402 $(TXT_TO_HTML) - >$@+ && \\\n> > 403 mv $@+ $@\n> \n> All of them seem to have dependencies so it seems to me that two\n> builds back to back without actually changing their input would not\n> re-build anything. What am I missing???\n\nPer default the files referenced do not exist, so a build from releases\nwill generate the files. But I agree, perhaps there should be some\nrefactoring to handle dependencies properly.\nIn any case, if the 'Last updated' is unavoidable some reference is\nrequired, see my patch in the other mail.\n\n> > What file timestamp should be used for them? Likely \"../version\"?\n> \n> I tend to think the \"Last updated\" timestamp taken from the\n> filesystem timestamp is a bad practice inherited by these tools from\n> the days back when nobody used any revision control systems.\n\nI'm not sure. The bug is that such 'Last updated' line exists at all in\nthe default output. Noone asked for it, noone really needs it. And it\nmakes it impossible to get reproducible builds.\nBut so far I found no way to avoid the 'Last updated' output. The docs\nand google suggest something like :last-updated-time!:, which did not\nwork for me.\n\nOlaf\n"},{"id":"255396","messageId":"xmqqbnlif6t9.fsf@gitster.dls.corp.google.com","threadId":"38455","inReplyTo":"20150128080214.GA18851@aepfle.de","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-01-29T06:18:42Z","receivedAt":"2015-01-29T06:18:42Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Olaf Hering writes:\n\n> On Tue, Jan 27, Junio C Hamano wrote:\n>\n>> > What file timestamp should be used for them? Likely \"../version\"?\n>> \n>> I tend to think the \"Last updated\" timestamp taken from the\n>> filesystem timestamp is a bad practice inherited by these tools from\n>> the days back when nobody used any revision control systems.\n>\n> I'm not sure. The bug is that such 'Last updated' line exists at all in\n> the default output. Noone asked for it, noone really needs it. And it\n> makes it impossible to get reproducible builds.\n\nAmen to that ;-)\n"},{"id":"255430","messageId":"54CB5770.8030503@drmicha.warpmail.net","threadId":"38455","inReplyTo":"xmqqbnlif6t9.fsf@gitster.dls.corp.google.com","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2015-01-30T10:05:36Z","receivedAt":"2015-01-30T10:05:36Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano schrieb am 29.01.2015 um 07:18:\n> Olaf Hering writes:\n> \n>> On Tue, Jan 27, Junio C Hamano wrote:\n>>\n>>>> What file timestamp should be used for them? Likely \"../version\"?\n>>>\n>>> I tend to think the \"Last updated\" timestamp taken from the\n>>> filesystem timestamp is a bad practice inherited by these tools from\n>>> the days back when nobody used any revision control systems.\n>>\n>> I'm not sure. The bug is that such 'Last updated' line exists at all in\n>> the default output. Noone asked for it, noone really needs it. And it\n>> makes it impossible to get reproducible builds.\n> \n> Amen to that ;-)\n> \n\nIt's a shame one can't simply replace the [footer-text] template which\nasciidoc insists on.\n\nIt turns out asciidoc 8.6.9-3 and later will habe a knob to turn:\n\nhttps://github.com/asciidoc/asciidoc/pull/9\n\nI'll try and get my hands on it to see whether we can simply use that.\nI'm wondering though which is more useful - the version of the tree the\ndoc is processed from, or the version of the last commit changing the\ncorresponding doc source file. The first one changes even when the doc\nsource is unchanged (but is stable between reruns, of course).\n\nMichael\n"},{"id":"255432","messageId":"20150130150758.GA3683@peff.net","threadId":"38455","inReplyTo":"54CB5770.8030503@drmicha.warpmail.net","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-01-30T15:07:58Z","receivedAt":"2015-01-30T15:07:58Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Jan 30, 2015 at 11:05:36AM +0100, Michael J Gruber wrote:\n\n> It's a shame one can't simply replace the [footer-text] template which\n> asciidoc insists on.\n> \n> It turns out asciidoc 8.6.9-3 and later will habe a knob to turn:\n> \n> https://github.com/asciidoc/asciidoc/pull/9\n> \n> I'll try and get my hands on it to see whether we can simply use that.\n> I'm wondering though which is more useful - the version of the tree the\n> doc is processed from, or the version of the last commit changing the\n> corresponding doc source file. The first one changes even when the doc\n> source is unchanged (but is stable between reruns, of course).\n\nI have 8.6.9-3 installed (it is part of Debian testing/unstable now),\nand confirmed that:\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 2c16c53..10c777e 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -21,6 +21,7 @@ tilde=~\n apostrophe='\n backtick=`\n litdd=--\n+footer-style=none\n \n ifdef::backend-docbook[]\n [linkgit-inlinemacro]\n\ndrops the \"last-updated\" footer.\n\nBut note that this only affects the generated HTML. The manpages still\nget the date in their footer. But this isn't an asciidoc-ism at all;\nit's added by docbook when converting the xml to roff. I'm sure there is\na way to tweak that, too, but looking at docbook gives me nightmares.\n\n-Peff\n"},{"id":"255883","messageId":"20150210151747.GA8965@aepfle.de","threadId":"38455","inReplyTo":"20150130150758.GA3683@peff.net","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Olaf Hering","fromEmail":"olaf@aepfle.de","sentAt":"2015-02-10T15:17:47Z","receivedAt":"2015-02-10T15:17:47Z","isPatch":false,"sender":{"key":"olaf@aepfle.de","avatar":"https://avatars.githubusercontent.com/u/942324?v=4"},"body":"On Fri, Jan 30, Jeff King wrote:\n\n> I have 8.6.9-3 installed (it is part of Debian testing/unstable now),\n> and confirmed that:\n> \n> diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\n> index 2c16c53..10c777e 100644\n> --- a/Documentation/asciidoc.conf\n> +++ b/Documentation/asciidoc.conf\n> @@ -21,6 +21,7 @@ tilde=~\n> apostrophe='\n> backtick=`\n> litdd=--\n> +footer-style=none\n> \n> ifdef::backend-docbook[]\n> [linkgit-inlinemacro]\n> \n> drops the \"last-updated\" footer.\n\nThis does not remove \"Last updated\" from files like\nusing-merge-subtree.html for me, using asciidoc-8.6.8.\n\nOlaf\n"},{"id":"255891","messageId":"20150210184318.GA20090@peff.net","threadId":"38455","inReplyTo":"20150210151747.GA8965@aepfle.de","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-02-10T18:43:18Z","receivedAt":"2015-02-10T18:43:18Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 10, 2015 at 04:17:47PM +0100, Olaf Hering wrote:\n\n> On Fri, Jan 30, Jeff King wrote:\n> \n> > I have 8.6.9-3 installed (it is part of Debian testing/unstable now),\n> > and confirmed that:\n> > \n> > diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\n> > index 2c16c53..10c777e 100644\n> > --- a/Documentation/asciidoc.conf\n> > +++ b/Documentation/asciidoc.conf\n> > @@ -21,6 +21,7 @@ tilde=~\n> > apostrophe='\n> > backtick=`\n> > litdd=--\n> > +footer-style=none\n> > \n> > ifdef::backend-docbook[]\n> > [linkgit-inlinemacro]\n> > \n> > drops the \"last-updated\" footer.\n> \n> This does not remove \"Last updated\" from files like\n> using-merge-subtree.html for me, using asciidoc-8.6.8.\n\nYes, the feature is part of 8.6.9-3.\n\n-Peff\n"},{"id":"300805","messageId":"20160901143736.GA26242@aepfle.de","threadId":"38455","inReplyTo":"20150210184318.GA20090@peff.net","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Olaf Hering","fromEmail":"olaf@aepfle.de","sentAt":"2016-09-01T14:37:36Z","receivedAt":"2016-09-01T14:37:49Z","isPatch":false,"sender":{"key":"olaf@aepfle.de","avatar":"https://avatars.githubusercontent.com/u/942324?v=4"},"body":"Hey, asciidoc made a move, so this patch is good to go:\nhttps://github.com/asciidoc/asciidoc/pull/9\n\nThanks.\n\nOlaf\n\nOn Tue, Feb 10, Jeff King wrote:\n\n> On Tue, Feb 10, 2015 at 04:17:47PM +0100, Olaf Hering wrote:\n> \n> > On Fri, Jan 30, Jeff King wrote:\n> > \n> > > I have 8.6.9-3 installed (it is part of Debian testing/unstable now),\n> > > and confirmed that:\n> > > \n> > > diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\n> > > index 2c16c53..10c777e 100644\n> > > --- a/Documentation/asciidoc.conf\n> > > +++ b/Documentation/asciidoc.conf\n> > > @@ -21,6 +21,7 @@ tilde=~\n> > > apostrophe='\n> > > backtick=`\n> > > litdd=--\n> > > +footer-style=none\n> > > \n> > > ifdef::backend-docbook[]\n> > > [linkgit-inlinemacro]\n> > > \n> > > drops the \"last-updated\" footer.\n> > \n> > This does not remove \"Last updated\" from files like\n> > using-merge-subtree.html for me, using asciidoc-8.6.8.\n> \n> Yes, the feature is part of 8.6.9-3.\n> \n> -Peff\n"},{"id":"300837","messageId":"20160901201738.qmitnvzo43wh6a6s@sigill.intra.peff.net","threadId":"38455","inReplyTo":"20160901143736.GA26242@aepfle.de","subject":"Re: implement a stable 'Last updated' in Documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-09-01T20:17:39Z","receivedAt":"2016-09-01T21:18:04Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 01, 2016 at 04:37:36PM +0200, Olaf Hering wrote:\n\n> Hey, asciidoc made a move, so this patch is good to go:\n> https://github.com/asciidoc/asciidoc/pull/9\n\nSine this thread is 18 months old, I needed some recap to remember what\nwe were talking about. :)\n\nIt's here:\n\n http://public-inbox.org/git/20150126172409.GA15204@aepfle.de/T/#u\n\nand the gist of it is that we'd like to drop the \"Last updated\" footer\nfrom the HTML version of the manpages, but older versions of asciidoc\ndid not provide a mechanism.\n\nThe patch you quoted adds \"footer-style=none\", which would do the trick.\nBut I have two open questions:\n\n 1. What does this do on older versions of asciidoc? Is it silently\n ignored (ok), or does it generate an error (bad)?\n\n 2. This covers the HTML versions, but not the roff manpages (which\n are generated by docbook). Do we have a way to tweak the date in\n the latter?\n\n I don't think that's necessarily a requirement for this patch, but\n it is worth thinking about at the same time.\n\nAssuming the answer to (1) is \"ok\" and (2) is \"no, but it's hard because\ndocbook is scary, so let's punt\", then somebody needs to write up the\ncommit message and send the actual patch to the list. Would you like to\ntry that?\n\n-Peff\n"}]}