Bug#790899: epydoc: please support timestamps from environment
On Mon, Jul 6, 2015 at 1:38 PM, Kenneth Pronovici prono...@debian.org wrote: On Thu, Jul 2, 2015 at 3:27 PM, Reiner Herrmann rei...@reiner-h.de wrote: Thanks for considering it! :) We uploaded also a patched epydoc to our repository today and are currently rebuilding affected packages [1]. The page should be updated soon. Ok, what you're asking for makes sense to me. I agree that it seems worthwhile to make these changes in Epydoc. I'm traveling this week for work. Unless Edward objects, I'll plan to apply the patch and upload a new package to unstable sometime after I'm back, hopefully no later than next weekend. I have filed a related bug in the upstream bug tracker: https://sourceforge.net/p/epydoc/bugs/368/ I updated the original patch to include man/epydoc.1, adding a section called REPRODUCIBLE BUILD BEHAVIOR. I also tweaked the patch description to better match the bug report I filed at SourceForge. I'll be uploading 3.0.1+dfsg-8 later today, including this patch. I have tested epydoc's general behavior, but I have not specifically tested the behavior around SOURCE_DATE_EPOCH. I am assuming you will tell me if the current version of the package does not meet your needs for the Reproducible Builds effort. Please let me know if you need anything else. KEN -- Kenneth J. Pronovici prono...@debian.org -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#790899: epydoc: please support timestamps from environment
On Thu, Jul 2, 2015 at 3:27 PM, Reiner Herrmann rei...@reiner-h.de wrote: Thanks for considering it! :) We uploaded also a patched epydoc to our repository today and are currently rebuilding affected packages [1]. The page should be updated soon. Ok, what you're asking for makes sense to me. I agree that it seems worthwhile to make these changes in Epydoc. I'm traveling this week for work. Unless Edward objects, I'll plan to apply the patch and upload a new package to unstable sometime after I'm back, hopefully no later than next weekend. KEN -- Kenneth J. Pronovici prono...@debian.org -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#790899: epydoc: please support timestamps from environment
Source: epydoc
Version: 3.0.1+dfsg-7
Severity: wishlist
Tags: patch
User: reproducible-bui...@lists.alioth.debian.org
Usertags: toolchain timestamps
X-Debbugs-Cc: reproducible-bui...@lists.alioth.debian.org
Hi!
In 3.0.1+dfsg-6 a patch has been added that allows packages to disable
embedding of timestamps.
But the default behavior of epydoc is to still embed timestamps (which requires
modifications
for each package using epydoc).
If timestamps have to be kept, we have a proposal for using deterministic ones
[1] (based on
the latest debian/changelog entry), which is contained in the environment
variable
SOURCE_DATE_EPOCH (which will hopefully soon be exported by debhelper).
The attached patch proposes a way to use this variable to get reproducible
timestamps, if the
variable has been set (if not, it falls back to the old behavior).
Regards,
Reiner
[1]: https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal
diff --git a/debian/patches/honour_source_date_epoch.patch b/debian/patches/honour_source_date_epoch.patch
new file mode 100644
index 000..31118f0
--- /dev/null
+++ b/debian/patches/honour_source_date_epoch.patch
@@ -0,0 +1,72 @@
+Author: Reiner Herrmann rei...@reiner-h.de
+Description: Honour SOURCE_DATE_EPOCH if available
+ Using the current date for timestamps will produce unreproducible
+ manpages. If the environment variable SOURCE_DATE_EPOCH is set,
+ as proposed by the Reproducible Builds effort [1], a deterministic
+ timestamp is avilable that can be used to embed dates.
+ .
+ [1]: https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal
+
+Index: epydoc-3.0.1+dfsg/epydoc/docwriter/html.py
+===
+--- epydoc-3.0.1+dfsg.orig/epydoc/docwriter/html.py
epydoc-3.0.1+dfsg/epydoc/docwriter/html.py
+@@ -433,6 +433,14 @@ class HTMLWriter:
+ and d.container == doc]
+ self.indexed_docs.sort()
+
++# set build time
++self._build_time = time.gmtime()
++if os.environ.has_key('SOURCE_DATE_EPOCH'):
++try:
++self._build_time = time.gmtime(int(os.environ['SOURCE_DATE_EPOCH']))
++except ValueError:
++pass
++
+ # Figure out the url for the top page.
+ self._top_page_url = self._find_top_page(self._top_page)
+
+@@ -1780,7 +1788,7 @@ class HTMLWriter:
+#endif
+ Generated by Epydoc $epydoc.__version__$
+ if self._include_build_time:
+-on $time.asctime()$
++on $time.asctime(self._build_time)$
+ #endif
+if self._include_log:
+ /a
+Index: epydoc-3.0.1+dfsg/epydoc/docwriter/latex.py
+===
+--- epydoc-3.0.1+dfsg.orig/epydoc/docwriter/latex.py
epydoc-3.0.1+dfsg/epydoc/docwriter/latex.py
+@@ -14,7 +14,7 @@ this module is the L{LatexWriter} class.
+
+ __docformat__ = 'epytext en'
+
+-import os.path, sys, time, re, textwrap, codecs
++import os.path, os, sys, time, re, textwrap, codecs
+
+ from epydoc.apidoc import *
+ from epydoc.compat import *
+@@ -1099,6 +1099,12 @@ class LatexWriter:
+ #
+
+ def write_header(self, out, where):
++build_time = time.gmtime()
++if os.environ.has_key('SOURCE_DATE_EPOCH'):
++try:
++build_time = time.gmtime(int(os.environ['SOURCE_DATE_EPOCH']))
++except ValueError:
++pass
+ out('%\n% API Documentation')
+ if self._prj_name: out(' for %s' % self._prj_name)
+ if isinstance(where, APIDoc):
+@@ -1106,7 +1112,7 @@ class LatexWriter:
+ else:
+ out('\n%% %s' % where)
+ out('\n%%\n%% Generated by epydoc %s\n' % epydoc.__version__)
+-out('%% [%s]\n%%\n' % time.asctime(time.localtime(time.time(
++out('%% [%s]\n%%\n' % time.asctime(build_time))
+
+ def write_start_of(self, out, section_name):
+ out('\n' + 75*'%' + '\n')
diff --git a/debian/patches/series b/debian/patches/series
index 569c18b..582d009 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -7,3 +7,4 @@ python26-tokenizer.patch
special-latex-entries.patch
lintian.patch
build-time.patch
+honour_source_date_epoch.patch
signature.asc
Description: OpenPGP digital signature
Bug#790899: epydoc: please support timestamps from environment
On Thu, Jul 2, 2015 at 2:13 PM, Reiner Herrmann rei...@reiner-h.de wrote: In 3.0.1+dfsg-6 a patch has been added that allows packages to disable embedding of timestamps. But the default behavior of epydoc is to still embed timestamps (which requires modifications for each package using epydoc). If timestamps have to be kept, we have a proposal for using deterministic ones [1] (based on the latest debian/changelog entry), which is contained in the environment variable SOURCE_DATE_EPOCH (which will hopefully soon be exported by debhelper). The attached patch proposes a way to use this variable to get reproducible timestamps, if the variable has been set (if not, it falls back to the old behavior). Hi Reiner, I have been following the reproducible builds effort. I appreciate you providing this patch. However, I have some concerns with it. My main concern is that this patch adds some rather Debian-specific behavior to epydoc. I'm not entirely comfortable with this, given that eypdoc is a general-purpose tool which just happens to be used when building some Debian packages. Adding a new command-line switch is one thing, but changing behavior to respond silently to a environment variable feels different to me. This would be the only environment variable that epydoc pays any attention to. I skimmed through the comments in #787444, and I gather that help2man has added support for this environment variable. Are you filing similar bugs with other documentation-generator packages in Debian? Have other packages committed to supporting it? Are you expecting this to become a standard used by other Linux distributions? It seems like relatively few Debian packages use epydoc as part of their build process. I guess I'm questioning whether it's really worth adding this Debian-specific behavior just to avoid changing those packages. I'm not saying no, but I would like to get a better handle on some of these questions before I apply the patch and release a new package. I've also CC'd upstream (Edward Loper) to see if he has an opinion one way or the other. Thanks, KEN -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#790899: epydoc: please support timestamps from environment
Hi Ken and Edward, On Thu, Jul 02, 2015 at 02:56:19PM -0500, Kenneth Pronovici wrote: I have been following the reproducible builds effort. I appreciate you providing this patch. However, I have some concerns with it. My main concern is that this patch adds some rather Debian-specific behavior to epydoc. I'm not entirely comfortable with this, given that eypdoc is a general-purpose tool which just happens to be used when building some Debian packages. Adding a new command-line switch is one thing, but changing behavior to respond silently to a environment variable feels different to me. This would be the only environment variable that epydoc pays any attention to. In our opinion it would be best if no timestamps were embedded at all (by default), since they don't provide users any meaningful information. But this makes it harder to convince upstreams to adopt it. A slightly different behavior during package building (and in all other cases having the old behavior) is probably easier to upstream. I skimmed through the comments in #787444, and I gather that help2man has added support for this environment variable. Are you filing similar bugs with other documentation-generator packages in Debian? Have other packages committed to supporting it? Are you expecting this to become a standard used by other Linux distributions? We only recently started experimenting with this, so until now there are no other packages besides help2man supporting it. Since today we have a modified debhelper in our experimental toolchain repository which exports this variable. Another patch was also submitted for txt2man (#790801), and more patches for other documentation generators / toolchain packages will be submitted in the future. And yes, we hope that this will become a standard used also by other distributions (that's why we chose a neutral name). It seems like relatively few Debian packages use epydoc as part of their build process. I guess I'm questioning whether it's really worth adding this Debian-specific behavior just to avoid changing those packages. In my opinions it's better to fix the root of the problems instead of adapting each affected package. And we hope that it won't remain something Debian-specific. I'm not saying no, but I would like to get a better handle on some of these questions before I apply the patch and release a new package. I've also CC'd upstream (Edward Loper) to see if he has an opinion one way or the other. Thanks for considering it! :) We uploaded also a patched epydoc to our repository today and are currently rebuilding affected packages [1]. The page should be updated soon. Kind regards, Reiner [1]: https://reproducible.debian.net/issues/unstable/use_epydoc_issue.html signature.asc Description: Digital signature
