Merge lp:~richard-wilbur/bzr/1537319-reproducible-builds into lp:bzr

[Richard Wilbur]

Changes to support GNU and debian reproducible builds effort: Add functionality to version-info to make populating SOURCE_DATE_EPOCH trivial on a bzr branch. Modify build and packaging code and rules to make bzr deliver reproducible builds for the same build environment.
Fixes lp:1537319

[Richard Wilbur (richard-wilbur)]

I have nothing against 'bzr version-info --source-date-epoch' but I figured some folks might complain about the length of the required command line so I implemented (and documented) a hard-coded alias 'bzr sde' for that command. This is for those who value compactness over verbosity.

[lp:~richard-wilbur/bzr/1537319-reproducible-builds]

6615. By Richard Wilbur on 2016-02-01

Change makefile rules for reproducible input order. Use SOURCE_DATE_EPOCH for generating timestamps and datestamps, if available. Otherwise forgo timestamps and datestamps. Use SOURCE_DATE_EPOCH to clamp file modification times when generating tarball. Use root user and group as numeric id 0 when generating tarball.

6616. By Richard Wilbur on 2016-02-01

Fix creation of date and time stamps. man pages always have a datestamp in title so, in the absence of SOURCE_DATE_EPOCH, give the impossible date of 1 second before the UNIX epoch.

[Vincent Ladeuil (vila)]

Hmm.

This looks like a rabbit hole :-/

Overall, this is going in the right direction but I think this will end up in several MPs.

There is duplicated code you're modifying which is worth refactoring as are the duplicate doc Makefiles.

Not to mention the comments (I feel your pain :-/) you had to modify to maintain consistency.

And we need more tests :) At least a setup where we can build all docs and see the results to start with.

[Richard Wilbur (richard-wilbur)]

I'm happy to accommodate multiple merge proposals but am in need of counsel on how best to accomplish that. Should I shelve everything except one changeset, polish, push to launchpad, propose the merge, review, merge, and repeat? Using the same branch? Should I break the changes into separate branches?

I see the main changes here as:
revision 6614: Add explicit support to bzr for creating SOURCE_DATE_EPOCH from a bzr branch. (If no version information is available, presently returns 0 => *nix epoch. Would a different value be more suitable?)

revision 6615:
./Makefile: Change make rules to sort the file lists for constant file order in tar file creation. Also use numeric user and group ids, root/root => 0/0 and clamp modification time to SOURCE_DATE_EPOCH when creating tar files. (Set SOURCE_DATE_EPOCH with `bzr sde` if not already set.)

./doc/en/Makefile: Use (or set with `bzr sde`) SOURCE_DATE_EPOCH to create BUILD_DATE for sphinx documentation build.

./bzrlib/doc_generate/autodoc_bash_completion.py: Try to get SOURCE_DATE_EPOCH and, if found, use it to create timestamp and include 'Last commit: %' in output file. Retitled from 'Generation time' to 'Last commit' as it seemed more descriptive.

./bzrlib/doc_generate/autodoc_man.py: Try to get SOURCE_DATE_EPOCH and, if found, use it to create date/time stamps. Split preamble and head so that datestamp and timestamp are only output when SOURCE_DATE_EPOCH is available.

./bzrlib/doc_generate/autodoc_rstx.py: Try to get SOURCE_DATE_EPOCH and, if found, use it to create date/time stamps. Split preamble so that timestamp is output when SOURCE_DATE_EPOCH is available.

revision 6616: Fixed syntax of date/time stamp creation in bzrlib/doc_generate/autodoc_*.py. Changed man head to always use datestamp but in the absence of SOURCE_DATE_EPOCH, use 1 second before the *nix epoch (valid, impossible date).

1. I see the utility of factoring common code out of the bzrlib/doc_generate/autodoc_*.py into bzrlib/doc_generate/__init__.py
If we decide to substitute a flag date/time for missing SOURCE_DATE_EPOCH information, this will greatly simplify the process of factoring out the common code (more will be common), and it will also simplify the code which creates the documentation as there won't be as many conditionally included pieces.

If so, what would be a good, fixed value to use as a flag date/time? I notice that I already return "0" from `bzr sde` if there is no revision information on the branch and use "-1" in the event we are missing SOURCE_DATE_EPOCH in the man documentation generator. I think a case could be made for these being materially similar situations: no revision information available. So I think it would benefit us to use a consistent flag for this situation. I like "-1" as it should never occur as a valid source date. The only issue would possibly occur if SOURCE_DATE_EPOCH were to be treated as an unsigned integer, in which case "0" would be preferrable. I expect "0" is pretty much equally unlikely to be a valid source date. (I suppose in Python we are relatively unlikely to ever find SOURCE_DATE_EPOCH treated as an unsigned integer. If we are interested i...

[Jelmer Vernooij (jelmer)]

Hi Richard,

Please split this up into separate merge proposals. At least for Debian, most of these changes are unnecessary. See https://tests.reproducible-builds.org/rb-pkg/unstable/amd64/bzr.html

[Richard Wilbur (richard-wilbur)]

Separate merge proposals on the same branch or do I need to create separate branches?

Unmerged revisions

6616. By Richard Wilbur on 2016-02-01

Fix creation of date and time stamps. man pages always have a datestamp in title so, in the absence of SOURCE_DATE_EPOCH, give the impossible date of 1 second before the UNIX epoch.

6615. By Richard Wilbur on 2016-02-01

Change makefile rules for reproducible input order. Use SOURCE_DATE_EPOCH for generating timestamps and datestamps, if available. Otherwise forgo timestamps and datestamps. Use SOURCE_DATE_EPOCH to clamp file modification times when generating tarball. Use root user and group as numeric id 0 when generating tarball.

6614. By Richard Wilbur on 2016-02-01

Add source-date-epoch format for version-info command (and alias sde) to support reproducible builds.

=== modified file 'Makefile'
--- Makefile	2012-03-09 16:48:55 +0000
+++ Makefile	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2011 Canonical Ltd
+# Copyright (C) 2005-2011, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -28,6 +28,10 @@
 PLUGIN_TARGET=plugin-release
 PYTHON_BUILDFLAGS=
 
+# Shorter replacement for $(sort $(wildcard <arg>)) as $(call sw,<arg>)
+sw = $(sort $(wildcard $(1)))
+
+
 .PHONY: all clean realclean extensions pyflakes api-docs check-nodocs check
 
 all: extensions
@@ -106,10 +110,10 @@
 ### Man-page Documentation ###
 
 MAN_DEPENDENCIES = bzrlib/builtins.py \
-	$(wildcard bzrlib/*.py) \
-	$(wildcard bzrlib/*/*.py) \
+	$(call sw,bzrlib/*.py) \
+	$(call sw,bzrlib/*/*.py) \
 	tools/generate_docs.py \
-	$(wildcard $(addsuffix /*.txt, bzrlib/help_topics/en)) 
+	$(call sw,$(addsuffix /*.txt, bzrlib/help_topics/en)) 
 
 MAN_PAGES = man1/bzr.1
 man1/bzr.1: $(MAN_DEPENDENCIES)
@@ -145,7 +149,7 @@
 	doc/developers/Makefile \
 	doc/developers/make.bat
 
-NEWS_FILES = $(wildcard doc/en/release-notes/bzr-*.txt)
+NEWS_FILES = $(call sw,doc/en/release-notes/bzr-*.txt)
 
 doc/en/user-reference/index.txt: $(MAN_DEPENDENCIES)
 	$(PYTHON) tools/generate_docs.py -o $@ rstx
@@ -229,19 +233,19 @@
 	doc/en/tutorials/tutorial.txt \
 	doc/en/tutorials/using_bazaar_with_launchpad.txt \
 	doc/en/tutorials/centralized_workflow.txt \
-        $(wildcard doc/es/tutorials/*.txt) \
-		$(wildcard doc/ru/tutorials/*.txt) \
+        $(call sw,doc/es/tutorials/*.txt) \
+	$(call sw,doc/ru/tutorials/*.txt) \
 	doc/ja/tutorials/tutorial.txt \
 	doc/ja/tutorials/using_bazaar_with_launchpad.txt \
 	doc/ja/tutorials/centralized_workflow.txt \
-	$(wildcard doc/*/mini-tutorial/index.txt) \
-	$(wildcard doc/*/user-guide/index-plain.txt) \
+	$(call sw,doc/*/mini-tutorial/index.txt) \
+	$(call sw,doc/*/user-guide/index-plain.txt) \
 	doc/en/admin-guide/index-plain.txt \
-	$(wildcard doc/es/guia-usario/*.txt) \
+	$(call sw,doc/es/guia-usario/*.txt) \
 	$(derived_txt_files) \
 	doc/en/upgrade-guide/index.txt \
 	doc/index.txt \
-	$(wildcard doc/index.*.txt)
+	$(call sw,doc/index.*.txt)
 txt_nohtml = \
 	doc/en/user-guide/index.txt \
 	doc/es/user-guide/index.txt \
@@ -253,16 +257,16 @@
 
 non_txt_files = \
        doc/default.css \
-       $(wildcard doc/*/bzr-en-quick-reference.svg) \
-       $(wildcard doc/*/bzr-en-quick-reference.png) \
-       $(wildcard doc/*/bzr-en-quick-reference.pdf) \
-       $(wildcard doc/*/bzr-es-quick-reference.svg) \
-       $(wildcard doc/*/bzr-es-quick-reference.png) \
-       $(wildcard doc/*/bzr-es-quick-reference.pdf) \
-       $(wildcard doc/*/bzr-ru-quick-reference.svg) \
-       $(wildcard doc/*/bzr-ru-quick-reference.png) \
-       $(wildcard doc/*/bzr-ru-quick-reference.pdf) \
-       $(wildcard doc/*/user-guide/images/*.png)
+       $(call sw,doc/*/bzr-en-quick-reference.svg) \
+       $(call sw,doc/*/bzr-en-quick-reference.png) \
+       $(call sw,doc/*/bzr-en-quick-reference.pdf) \
+       $(call sw,doc/*/bzr-es-quick-reference.svg) \
+       $(call sw,doc/*/bzr-es-quick-reference.png) \
+       $(call sw,doc/*/bzr-es-quick-reference.pdf) \
+       $(call sw,doc/*/bzr-ru-quick-reference.svg) \
+       $(call sw,doc/*/bzr-ru-quick-reference.png) \
+       $(call sw,doc/*/bzr-ru-quick-reference.pdf) \
+       $(call sw,doc/*/user-guide/images/*.png)
 
 # doc/developers/*.txt files that should *not* be individually
 # converted to HTML
@@ -292,20 +296,20 @@
 	doc/developers/status.txt \
 	doc/developers/uncommit.txt
 
-dev_txt_all = $(wildcard $(addsuffix /*.txt, doc/developers))
+dev_txt_all = $(call sw,$(addsuffix /*.txt, doc/developers))
 dev_txt_files = $(filter-out $(dev_txt_nohtml), $(dev_txt_all))
 dev_htm_files = $(patsubst %.txt, %.html, $(dev_txt_files)) 
 
-doc/en/user-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/user-guide)) 
+doc/en/user-guide/index-plain.html: $(call sw,$(addsuffix /*.txt, doc/en/user-guide))
 	$(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
 
-#doc/es/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/es/user-guide)) 
-#	$(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
-#
-#doc/ru/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/ru/user-guide)) 
-#	$(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
-#
-doc/en/admin-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/admin-guide)) 
+#doc/es/user-guide/index.html: $(call sw,$(addsuffix /*.txt, doc/es/user-guide))
+#	$(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
+#
+#doc/ru/user-guide/index.html: $(call sw,$(addsuffix /*.txt, doc/ru/user-guide))
+#	$(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
+#
+doc/en/admin-guide/index-plain.html: $(call sw,$(addsuffix /*.txt, doc/en/admin-guide))
 	$(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
 
 doc/developers/%.html: doc/developers/%.txt
@@ -323,7 +327,7 @@
 doc/en/release-notes/NEWS.txt: $(NEWS_FILES) tools/generate_release_notes.py
 	$(PYTHON) tools/generate_release_notes.py "$@" $(NEWS_FILES)
 
-upgrade_guide_dependencies =  $(wildcard $(addsuffix /*.txt, doc/en/upgrade-guide)) 
+upgrade_guide_dependencies =  $(call sw,$(addsuffix /*.txt, doc/en/upgrade-guide))
 
 doc/en/upgrade-guide/index.html: $(upgrade_guide_dependencies)
 	$(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
@@ -435,8 +439,9 @@
 update-pot: po/bzr.pot
 
 TRANSLATABLE_PYFILES:=$(shell find bzrlib -name '*.py' \
-    		| grep -v 'bzrlib/tests/' \
-    		| grep -v 'bzrlib/doc' \
+		| grep -v 'bzrlib/tests/' \
+		| grep -v 'bzrlib/doc' \
+		| LC_ALL=C sort \
 		)
 
 po/bzr.pot: $(PYFILES) $(DOCFILES)
@@ -453,6 +458,12 @@
 
 .PHONY: dist check-dist-tarball
 
+SOURCE_DATE_EPOCH ?= $(shell bzr sde)
+TAR_OPTS = "--sort=name --owner=root --group=root --numeric-owner"
+ifdef SOURCE_DATE_EPOCH
+TAR_OPTS += "--mtime='$SOURCE_DATE_EPOCH' --clamp-mtime"
+endif
+
 # build a distribution source tarball
 #
 # this method of copying the pyrex generated files is a bit ugly; it would be
@@ -467,7 +478,7 @@
 	$(MAKE) && \
 	bzr export $$expdir && \
 	cp bzrlib/*.c bzrlib/*.h $$expdir/bzrlib/. && \
-	tar cfz $$tarball -C $$expbasedir bzr-$$version && \
+	tar $(TAR_OPTS) cfz $$tarball -C $$expbasedir bzr-$$version && \
 	gpg --detach-sign $$tarball && \
 	rm -rf $$expbasedir
 

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2013-05-23 10:04:17 +0000
+++ bzrlib/builtins.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2012 Canonical Ltd
+# Copyright (C) 2005-2012, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -6724,7 +6724,7 @@
         ('cmd_bundle_info', [], 'bzrlib.bundle.commands'),
         ('cmd_config', [], 'bzrlib.config'),
         ('cmd_dpush', [], 'bzrlib.foreign'),
-        ('cmd_version_info', [], 'bzrlib.cmd_version_info'),
+        ('cmd_version_info', ['sde'], 'bzrlib.cmd_version_info'),
         ('cmd_resolve', ['resolved'], 'bzrlib.conflicts'),
         ('cmd_conflicts', [], 'bzrlib.conflicts'),
         ('cmd_ping', [], 'bzrlib.smart.ping'),

=== modified file 'bzrlib/cmd_version_info.py'
--- bzrlib/cmd_version_info.py	2011-12-30 12:52:54 +0000
+++ bzrlib/cmd_version_info.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2011 Canonical Ltd
+# Copyright (C) 2005-2011, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -71,6 +71,14 @@
       * {branch_nick} - branch nickname
       * {clean} - 0 if the source tree contains uncommitted changes,
                   otherwise 1
+
+    In order to support reproducible builds, you can set the
+    SOURCE_DATE_EPOCH to the timestamp of the last commit on a bzr
+    working tree as follows:
+
+      SOURCE_DATE_EPOCH=$(bzr version-info --source-date-epoch)
+    or using the alias
+      SOURCE_DATE_EPOCH=$(bzr sde)
     """
 
     takes_options = [RegistryOption('format',
@@ -88,6 +96,7 @@
                      'revision',
                      ]
     takes_args = ['location?']
+    aliases = ['sde']
 
     encoding_type = 'exact'
 
@@ -96,6 +105,10 @@
             include_file_revisions=False, template=None,
             revision=None):
 
+        if 'sde' == self.invoked_as:
+            format = \
+                version_info_formats.format_registry.get(key=
+                                                         'source-date-epoch')
         if revision and len(revision) > 1:
             raise errors.BzrCommandError(
                 gettext('bzr version-info --revision takes exactly'

=== modified file 'bzrlib/doc_generate/autodoc_bash_completion.py'
--- bzrlib/doc_generate/autodoc_bash_completion.py	2011-12-19 13:23:58 +0000
+++ bzrlib/doc_generate/autodoc_bash_completion.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005 Canonical Ltd
+# Copyright (C) 2005, 2016 Canonical Ltd
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -18,7 +18,8 @@
 
 from __future__ import absolute_import
 
-import time
+import datetime
+import os
 
 import bzrlib
 import bzrlib.help
@@ -30,24 +31,35 @@
 
 
 def infogen(options, outfile):
-    t = time.time()
-    tt = time.gmtime(t)
-    params = \
-           { "bzrcmd": options.bzr_name,
-             "datestamp": time.strftime("%Y-%m-%d",tt),
-             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
-             "version": bzrlib.__version__,
-             }
+    try:
+        tt = datetime.datetime.utcfromtimestamp(int(os.environ['SOURCE_DATE_EPOCH']))
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 "datestamp": tt.strftime("%Y-%m-%d"),
+                 "timestamp": tt.strftime("%Y-%m-%d %H:%M:%S +0000"),
+                 "version": bzrlib.__version__,
+               }
+
+    except (KeyError, ValueError):
+        tt = None
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 "version": bzrlib.__version__,
+               }
 
     outfile.write(preamble % params)
+    if tt not None:
+        outfile.write(last_commit % params)
 
 
 preamble = """\
-# bash completion functions for for Bazaar (%(bzrcmd)s)
+# bash completion functions for Bazaar (%(bzrcmd)s)
 #
 # Large parts of this file are autogenerated from the internal
 # Bazaar documentation and data structures.
+"""
+
+last_commit = """\
 #
-# Generation time: %(timestamp)s
+# Last commit: %(timestamp)s
 """
-

=== modified file 'bzrlib/doc_generate/autodoc_man.py'
--- bzrlib/doc_generate/autodoc_man.py	2015-03-14 23:44:01 +0000
+++ bzrlib/doc_generate/autodoc_man.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2010 Canonical Ltd
+# Copyright (C) 2005-2010, 2016 Canonical Ltd
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -15,18 +15,15 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
 """man.py - create man page from built-in bzr help and static text
-
-TODO:
-  * use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
-  * add command aliases
 """
 
 from __future__ import absolute_import
 
 PLUGINS_TO_DOCUMENT = ["launchpad"]
 
+import datetime
+import os
 import textwrap
-import time
 
 import bzrlib
 import bzrlib.help
@@ -44,15 +41,35 @@
 
 def infogen(options, outfile):
     """Assembles a man page"""
-    t = time.time()
-    tt = time.gmtime(t)
-    params = \
-           { "bzrcmd": options.bzr_name,
-             "datestamp": time.strftime("%Y-%m-%d",tt),
-             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
-             "version": bzrlib.__version__,
-             }
-    outfile.write(man_preamble % params)
+    try:
+        tt = datetime.datetime.utcfromtimestamp(int(os.environ['SOURCE_DATE_EPOCH']))
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 "datestamp": tt.strftime("%Y-%m-%d"),
+                 "timestamp": tt.strftime("%Y-%m-%d %H:%M:%S +0000"),
+                 "version": bzrlib.__version__,
+               }
+        
+    except (KeyError, ValueError):
+        tt = None
+        ep = datetime.datetime.utcfromtimestamp(-1)
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 # Linux man-pages convention: Title includes
+                 # datestamp of last non-trivial revision.  In absence
+                 # of SOURCE_DATE_EPOCH use 1 second before UNIX
+                 # epoch (impossible date).
+                 "datestamp": ep.strftime("%Y-%m-%d"),
+                 "version": bzrlib.__version__,
+               }
+    # Split part of man_preamble out that uses timestamp to allow
+    # reproducible builds in the absence of SOURCE_DATE_EPOCH.
+    outfile.write(man_prepreamble % params)
+    if tt not None:
+        # Uses timestamp, if available.
+        outfile.write(man_last_commit_preamble % params)
+    outfile.write(man_postpreamble % params)
+
     outfile.write(man_escape(man_head % params))
     outfile.write(man_escape(getcommand_list(params)))
     outfile.write(man_escape(getcommand_help(params)))
@@ -182,13 +199,24 @@
         yield man_escape(desc) + "\n"
 
 
-man_preamble = """\
+# Split preamble to conditionally provide last commit time when
+# SOURCE_DATE_EPOCH provided by build system in order to provide
+# reproducible builds.
+man_prepreamble = """\
 .\\\"Man page for Bazaar (%(bzrcmd)s)
 .\\\"
 .\\\" Large parts of this file are autogenerated from the output of
 .\\\"     \"%(bzrcmd)s help commands\"
 .\\\"     \"%(bzrcmd)s help <cmd>\"
 .\\\"
+"""
+
+man_last_commit_preamble = """\
+.\\\" Last commit: %(timestamp)s
+.\\\"
+"""
+
+man_postpreamble = """\
 
 .ie \\n(.g .ds Aq \\(aq
 .el .ds Aq '

=== modified file 'bzrlib/doc_generate/autodoc_rstx.py'
--- bzrlib/doc_generate/autodoc_rstx.py	2015-11-15 02:30:05 +0000
+++ bzrlib/doc_generate/autodoc_rstx.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2006-2010 Canonical Ltd
+# Copyright (C) 2006-2010, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -22,7 +22,8 @@
 
 from __future__ import absolute_import
 
-import time
+import datetime
+import os
 
 import bzrlib
 import bzrlib.help
@@ -38,20 +39,34 @@
 
 def infogen(options, outfile):
     """Create manual in RSTX format"""
-    t = time.time()
-    tt = time.gmtime(t)
-    params = \
-           { "bzrcmd": options.bzr_name,
-             "datestamp": time.strftime("%Y-%m-%d",tt),
-             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
-             "version": bzrlib.__version__,
-             }
+    try:
+        tt = datetime.datetime.utcfromtimestamp(int(os.environ['SOURCE_DATE_EPOCH']))
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 "datestamp": tt.strftime("%Y-%m-%d"),
+                 "timestamp": tt.strftime("%Y-%m-%d %H:%M:%S +0000"),
+                 "version": bzrlib.__version__,
+               }
+        
+    except (KeyError, ValueError):
+        tt = None
+        params = \
+               { "bzrcmd": options.bzr_name,
+                 "version": bzrlib.__version__,
+               }
     nominated_filename = getattr(options, 'filename', None)
     if nominated_filename is None:
         topic_dir = None
     else:
         topic_dir = bzrlib.osutils.dirname(nominated_filename)
-    outfile.write(rstx_preamble % params)
+    # Split part of rstx_preamble out that uses timestamp to allow
+    # reproducible builds in the absence of SOURCE_DATE_EPOCH.
+    outfile.write(rstx_prepreamble % params)
+    if tt not None:
+        # Uses timestamp, if available.
+        outfile.write(rstx_last_commit_preamble % params)
+    outfile.write(rstx_postpreamble % params)
+
     outfile.write(rstx_head % params)
     outfile.write(_get_body(params, topic_dir))
     outfile.write(rstx_foot % params)
@@ -139,14 +154,24 @@
 ##
 # TEMPLATES
 
-rstx_preamble = """.. This file is autogenerated from the output of
+# Split preamble to conditionally provide last commit time when
+# SOURCE_DATE_EPOCH provided by build system in order to provide
+# reproducible builds.
+rstx_prepreamble = """\
+.. This file is autogenerated from the output of
 ..     %(bzrcmd)s help topics
 ..     %(bzrcmd)s help commands
 ..     %(bzrcmd)s help <cmd>
 ..
-
-"""
-
+"""
+
+rstx_last_commit_preamble = """\
+..  Last commit: %(timestamp)s
+"""
+
+rstx_postpreamble = """\
+
+"""
 
 rstx_head = """\
 #####################

=== modified file 'bzrlib/tests/test_version_info.py'
--- bzrlib/tests/test_version_info.py	2012-01-03 13:08:44 +0000
+++ bzrlib/tests/test_version_info.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2011 Canonical Ltd
+# Copyright (C) 2005-2011, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -33,6 +33,7 @@
 from bzrlib.version_info_formats.format_custom import CustomVersionInfoBuilder
 from bzrlib.version_info_formats.format_rio import RioVersionInfoBuilder
 from bzrlib.version_info_formats.format_python import PythonVersionInfoBuilder
+from bzrlib.version_info_formats.format_source_date_epoch import SourceDateEpochVersionInfoBuilder
 
 
 class VersionInfoTestCase(TestCaseWithTransport):
@@ -399,6 +400,34 @@
         self.assertRaises(errors.NoTemplate, builder.generate, sio)
 
 
+class SourceDateEpochVersionInfoTests(VersionInfoTestCase):
+
+    def test_custom_null(self):
+        """No revision yet on tree."""
+        sio = StringIO()
+        wt = self.make_branch_and_tree('branch')
+        builder = SourceDateEpochVersionInfoBuilder(wt.branch, working_tree=wt)
+        builder.generate(sio)
+        self.assertEquals("0", sio.getvalue())
+
+    def regen(self, wt):
+        sio = StringIO()
+        builder = SourceDateEpochVersionInfoBuilder(wt.branch, working_tree=wt)
+        builder.generate(sio)
+        val = sio.getvalue()
+        return val
+
+    def test_source_date_epoch(self):
+        """Should return seconds from *nix epoch till most recent revision."""
+        wt = self.create_branch()
+        # Get timestamp of most recent revision on tree.
+        br = wt.branch
+        revision_id = wt.last_revision()
+        last_rev = br.repository.get_revision(revision_id)
+        val = self.regen(wt)
+        self.assertEqual(val, '%0d' % last_rev.timestamp)
+
+
 class TestBuilder(version_info_formats.VersionInfoBuilder):
     pass
 

=== modified file 'bzrlib/version_info_formats/__init__.py'
--- bzrlib/version_info_formats/__init__.py	2011-12-30 13:02:27 +0000
+++ bzrlib/version_info_formats/__init__.py	2016-02-01 16:52:40 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005, 2006 Canonical Ltd
+# Copyright (C) 2005, 2006, 2016 Canonical Ltd
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -205,3 +205,8 @@
     'bzrlib.version_info_formats.format_custom',
     'CustomVersionInfoBuilder',
     'Version info in Custom template-based format.')
+format_registry.register_lazy(
+    'source-date-epoch',
+    'bzrlib.version_info_formats.format_source_date_epoch',
+    'SourceDateEpochVersionInfoBuilder',
+    'SOURCE_DATE_EPOCH version info (for reproducible builds).')

=== added file 'bzrlib/version_info_formats/format_source_date_epoch.py'
--- bzrlib/version_info_formats/format_source_date_epoch.py	1970-01-01 00:00:00 +0000
+++ bzrlib/version_info_formats/format_source_date_epoch.py	2016-02-01 16:52:40 +0000
@@ -0,0 +1,45 @@
+# Copyright (C) 2016 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+"""A generator which creates the SOURCE_DATE_EPOCH (seconds from the
+*nix epoch till the most recent revision commit) from the current tree
+info.  This is used to aid the reproducible builds effort by replacing
+date and time stamps derived from the build date and time with
+information regarding the last revision of the source code.
+"""
+
+from __future__ import absolute_import
+
+from bzrlib.revision import (
+    NULL_REVISION,
+    )
+from bzrlib.version_info_formats import (
+    VersionInfoBuilder,
+    )
+
+
+class SourceDateEpochVersionInfoBuilder(VersionInfoBuilder):
+    """Create a version file which consists of the source epoch."""
+
+    def generate(self, to_file):
+        revision_id = self._get_revision_id()
+        if revision_id == NULL_REVISION:
+            sde = 0
+        else:
+            rev = self._branch.repository.get_revision(revision_id)
+            sde = rev.timestamp
+
+        to_file.write('%0d' % sde)

=== modified file 'doc/en/Makefile'
--- doc/en/Makefile	2012-03-09 16:48:55 +0000
+++ doc/en/Makefile	2016-02-01 16:52:40 +0000
@@ -2,7 +2,9 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SOURCE_DATE_EPOCH ?= $(shell bzr sde)
+BUILD_DATE=$(shell LC_ALL=C date -u "+%B %d, %Y" -d "@$(SOURCE_DATE_EPOCH)")
+SPHINXOPTS    = "-D today=\"$(BUILD_DATE)\""
 SPHINXBUILD   = sphinx-build
 PAPER         =