[Git][reproducible-builds/reproducible-website][master] 3 commits: Update SOURCE_DATE_EPOCH documentation re. datetime.datetime.fromtimestamp....
Chris Lamb (@lamby)
gitlab at salsa.debian.org
Thu Feb 22 13:47:15 UTC 2024
Chris Lamb pushed to branch master at Reproducible Builds / reproducible-website
Commits:
502769f1 by Chris Lamb at 2024-02-22T13:34:46+00:00
Update SOURCE_DATE_EPOCH documentation re. datetime.datetime.fromtimestamp. Thanks, James Addison! (Closes: #50)
- - - - -
05a76405 by Chris Lamb at 2024-02-22T13:46:06+00:00
Re-order and punch up a bunch of stuff on the SOURCE_DATE_EPOCH page
- - - - -
3243e14b by Chris Lamb at 2024-02-22T13:46:45+00:00
Improve the relative sizing of headers.
- - - - -
2 changed files:
- _docs/source-date-epoch.md
- assets/styles/custom.scss
Changes:
=====================================
_docs/source-date-epoch.md
=====================================
@@ -5,118 +5,52 @@ permalink: /docs/source-date-epoch/
---
-`SOURCE_DATE_EPOCH` is a [standardised environment variable](https://reproducible-builds.org/specs/source-date-epoch/) that distributions can set centrally and have build tools consume this in order to produce reproducible output.
+`SOURCE_DATE_EPOCH` is a [standardised environment variable](https://reproducible-builds.org/specs/source-date-epoch/) that distributions can set centrally and have build tools consume this in order to produce reproducible output. In practice, `SOURCE_DATE_EPOCH` specifies the last modification of something, usually the source code, measured in the number seconds since the Unix epoch, ie. `January 1st 1970, 00:00:00 UTC`.
-In practice `SOURCE_DATE_EPOCH` specifies the last modification of something, usually the source code, (measured) in seconds since the Unix epoch, which is January 1st 1970, 00:00:00 UTC.
-
-Before implementing this, you should scan through [our checklist](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables#Checklist) to see if you can avoid implementing it.
-
-If you find that it's ideal for your use-case, please feel free to jump straight to our **[published specification](https://reproducible-builds.org/specs/source-date-epoch/)**.
-
-## Proposal
-
-Please read our [SOURCE_DATE_EPOCH specification](https://reproducible-builds.org/specs/source-date-epoch/) for details.
-
-See [Standard Environment Variables](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables) for more detailed discussion of the rationales behind this mechanism.
-
-Below we also have more detailed discussion about this specific variable, as well as documentation on history and alternative proposals.
-
-## Setting the variable
-
-### Debian
-
-In Debian, this is automatically set to the same time as the latest entry in `debian/changelog`, i.e. the same as the output of `dpkg-parsechangelog -SDate`.
-
- 1. For packages using debhelper, versions >= 9.20151004 (Bug:791823) exports this variable during builds, so you probably don't need to change anything. One exception is if your `debian/rules` needs this variable in non-debhelper parts, in which case you can try (3) or (4).
-
- 2. For packages using CDBS, versions >= 0.4.131 (Bug:794241) exports this variable during builds, so no changes are needed.
-
- 3. With dpkg >= 1.18.8 (Bug:824572) you can either `include /usr/share/dpkg/pkg-info.mk` or `include /usr/share/dpkg/default.mk`.
-
- 4. If none of the above options are good (you should have a ''very good reason'') then package maintainers may set and export this variable manually in `debian/rules`:
-
- ```
- export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -STimestamp)
- ```
-
- If you need/want to support dpkg versions earlier than 1.18.8:
-
- ```
- export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -SDate | date -f- +%s)
- ```
-
- If you need/want to support dpkg versions earlier than 1.17.0:
-
- ```
- export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog | grep -Po '^Date: \K.*' | date -f- +%s)
- ```
-
- This snippet is believed to work on dpkg versions as far back as 2003.
-
-### Git
-
-To set SOURCE_DATE_EPOCH to the last modification of a git repository you can use 'git log', for example in shell:
-
-```
-SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
-```
+Before added support to a tool for reading this variable, you should scan through [Debian's checklist](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables#Checklist) to see if you can avoid implementing it: a number of tools already will do this for you. However, if you find that it's ideal for your use-case, please feel free to jump straight to our **[published specification](https://reproducible-builds.org/specs/source-date-epoch/)**.
## Reading the variable
-We are persuading upstream tools to support this directly. You may help by writing patches for these tools; please add links to the bug reports here so we know, and to act as an example resource for future patch writers.
-
- Pending:: none
-
- Complete::
- * [busybox](http://lists.busybox.net/pipermail/busybox/2021-June/088880.html) (>1.33.1)
- * [cmake](https://gitlab.kitware.com/cmake/cmake/merge_requests/432) (>= 3.8.0)
- * [debhelper](https://bugs.debian.org/791823) (>= 9.20151004)
- * [distro-info](https://bugs.debian.org/1034422) (>= 1.6)
- * [docbook-utils](https://bugs.debian.org/800797) (Debian >= 0.6.14-3.1, upstream TODO)
- * [doxygen](https://bugs.debian.org/792201) (>= [1.8.12](https://github.com/doxygen/doxygen/commit/9a2c7bbfb0c53b4532db7280e6804c7ce76d70a3), Debian pending)
- * [epydoc](https://bugs.debian.org/790899) (>= 3.0.1+dfsg-8, upstream [pending](https://sourceforge.net/p/epydoc/bugs/368/))
- * [gettext](https://bugs.debian.org/792687) (>=0.20)
- * [gcc](https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff;h=e3e8c48c4a494d9da741c1c8ea6c4c0b7c4ff934) (>= 7, Debian >= 5.3.1-17, Debian >= 6.1.1-1)
- * [ghostscript](https://bugs.debian.org/794004) (Debian >= 9.16~dfsg-1, upstream [unfortunately rejected](http://bugs.ghostscript.com/show_bug.cgi?id=696765) due to additional constraints they have)
- * [groff](https://bugs.debian.org/762854) (Debian >= 1.22.3-2, upstream [pending](https://lists.gnu.org/archive/html/groff/2015-11/msg00038.html))
- * [help2man](https://bugs.debian.org/787444) (>= 1.47.1)
- * [libxslt](https://bugs.debian.org/791815) (>= [1.1.29](https://bugzilla.gnome.org/show_bug.cgi?id=758148), Debian >= 1.1.28-3)
- * [man2html](https://bugs.debian.org/796130) (Debian >= 1.6g-8, [needs forwarding](https://sources.debian.net/src/man2html/1.6g-8/debian/patches/035-source-date-epoch.patch/))
- * [mkdocs](https://bugs.debian.org/824266) (>= [0.16](https://github.com/mkdocs/mkdocs/pull/939/commits/8b006bd7fda55e47e29412896c511c7244398f82), Debian pending)
- * [ocamldoc](https://bugs.debian.org/794586) (>= [4.03.0](https://github.com/ocaml/ocaml/commit/0319173b7d02008e4ce6b81dceaf7c32cf5f8a6f), Debian >= 4.02.3-1)
- * [pydoctor](https://bugs.debian.org/807166) (>= 0.5+git20151204)
- * [rpm upstream](https://github.com/rpm-software-management/rpm/pull/144) (>4.13 other relevant patches linked in there)
- * [sphinx](https://github.com/sphinx-doc/sphinx/pull/1954) (>= 1.4, Debian >= 1.3.1-3)
- * [texi2html](https://bugs.debian.org/783475) (Debian >= 1.82+dfsg1-4, [needs forwarding](https://sources.debian.net/src/texi2html/1.82%2Bdfsg1-5/debian/patches/05_reproducible-build/))
- * [texlive-bin](https://bugs.debian.org/792202) (>= 2016.20160512.41045)
- * [txt2man](https://bugs.debian.org/790801) (>= [1.5.7](https://github.com/mvertes/txt2man/pull/1), Debian >= 1.5.6-4)
- * [rcc](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=894476) (Qt5 >= [5.13.0](https://code.qt.io/cgit/qt/qtbase.git/commit/?id=1ffcca4cc208c48ddb06b6a23abf1756f9724351), Debian TODO)
-
-Or search in all Debian sources: <https://codesearch.debian.net/search?perpkg=1&q=SOURCE_DATE_EPOCH>
-
-### Python
+### Python >= 3.x
```
import os
import time
import datetime
-build_date = datetime.datetime.utcfromtimestamp(
- int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
+build_date = datetime.datetime.fromtimestamp(
+ int(os.environ.get('SOURCE_DATE_EPOCH', time.time())),
+ tz=datetime.timezone.utc,
)
```
-or with less imports, rendering to a string:
+… or with fewer imports and rendering to a string:
```
import os
import time
+
date_str = time.strftime(
"%Y-%m-%d",
time.gmtime(int(os.environ.get('SOURCE_DATE_EPOCH', time.time())))
)
```
+### Python >= 2.x
+
+If you still require Python 2.x support, you will need to use the non-recommended [`datetime.utcfromtimestamp`](https://docs.python.org/3.8/library/datetime.html#datetime.datetime.utcfromtimestamp) method ([more info](https://blog.ganssle.io/articles/2019/11/utcnow.html)):
+
+
+```
+import os
+import time
+import datetime
+
+build_date = datetime.datetime.utcfromtimestamp(
+ int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
+)
+```
+
### Bash / POSIX shell
For GNU systems:
@@ -442,6 +376,80 @@ TODO: document some other nicer options. Generally, all invocations of `date(1)`
NOTE: faketime BREAKS builds on some archs, for example hurd. See #778462 for details.
+## Setting the variable
+
+### Debian
+
+In Debian, this is automatically set to the same time as the latest entry in `debian/changelog`, i.e. the same as the output of `dpkg-parsechangelog -SDate`.
+
+1. For packages using `debhelper` versions >= 9.20151004, [this variable is automatically exported during builds](https://bugs.debian.org/791823), so you probably don't need to change anything. One exception is if your `debian/rules` needs this variable in non-debhelper parts, in which case you can try (3) or (4).
+
+2. For packages using CDBS, versions >= 0.4.131 [this variable is also exported automatically during builds](https://bugs.debian.org/794241), so no changes are needed.
+
+3. With `dpkg` >= 1.18.8 you can either `include /usr/share/dpkg/pkg-info.mk` or `include /usr/share/dpkg/default.mk`. This was added in Debian bug [#824572](https://bugs.debian.org/824572).
+
+4. If none of the above options are good (you should have a ''very good reason'') then package maintainers may set and export this variable manually in `debian/rules`:
+
+ ```
+ export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -STimestamp)
+ ```
+
+ If you need/want to support dpkg versions earlier than 1.18.8:
+
+ ```
+ export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -SDate | date -f- +%s)
+ ```
+
+ If you need/want to support dpkg versions earlier than 1.17.0:
+
+ ```
+ export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog | grep -Po '^Date: \K.*' | date -f- +%s)
+ ```
+
+ This snippet is believed to work on dpkg versions as far back as 2003.
+
+### Git
+
+To set `SOURCE_DATE_EPOCH` to the last modification of a Git repository you can use `git log`. For example:
+
+```
+export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
+```
+
+
+### Tool support
+
+We are persuading upstream tools to support `SOURCE_DATE_EPOCH` directly. You may help by writing patches for these tools; please add links to the bug reports here so we know, and to act as an example resource for future patch writers.
+
+Complete:
+
+* [busybox](http://lists.busybox.net/pipermail/busybox/2021-June/088880.html) (>1.33.1)
+* [cmake](https://gitlab.kitware.com/cmake/cmake/merge_requests/432) (>= 3.8.0)
+* [debhelper](https://bugs.debian.org/791823) (>= 9.20151004)
+* [distro-info](https://bugs.debian.org/1034422) (>= 1.6)
+* [docbook-utils](https://bugs.debian.org/800797) (Debian >= 0.6.14-3.1, upstream TODO)
+* [doxygen](https://bugs.debian.org/792201) (>= [1.8.12](https://github.com/doxygen/doxygen/commit/9a2c7bbfb0c53b4532db7280e6804c7ce76d70a3), Debian pending)
+* [epydoc](https://bugs.debian.org/790899) (>= 3.0.1+dfsg-8, upstream [pending](https://sourceforge.net/p/epydoc/bugs/368/))
+* [gettext](https://bugs.debian.org/792687) (>=0.20)
+* [gcc](https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff;h=e3e8c48c4a494d9da741c1c8ea6c4c0b7c4ff934) (>= 7, Debian >= 5.3.1-17, Debian >= 6.1.1-1)
+* [ghostscript](https://bugs.debian.org/794004) (Debian >= 9.16~dfsg-1, upstream [unfortunately rejected](http://bugs.ghostscript.com/show_bug.cgi?id=696765) due to additional constraints they have)
+* [groff](https://bugs.debian.org/762854) (Debian >= 1.22.3-2, upstream [pending](https://lists.gnu.org/archive/html/groff/2015-11/msg00038.html))
+* [help2man](https://bugs.debian.org/787444) (>= 1.47.1)
+* [libxslt](https://bugs.debian.org/791815) (>= [1.1.29](https://bugzilla.gnome.org/show_bug.cgi?id=758148), Debian >= 1.1.28-3)
+* [man2html](https://bugs.debian.org/796130) (Debian >= 1.6g-8, [needs forwarding](https://sources.debian.net/src/man2html/1.6g-8/debian/patches/035-source-date-epoch.patch/))
+* [mkdocs](https://bugs.debian.org/824266) (>= [0.16](https://github.com/mkdocs/mkdocs/pull/939/commits/8b006bd7fda55e47e29412896c511c7244398f82), Debian pending)
+* [ocamldoc](https://bugs.debian.org/794586) (>= [4.03.0](https://github.com/ocaml/ocaml/commit/0319173b7d02008e4ce6b81dceaf7c32cf5f8a6f), Debian >= 4.02.3-1)
+* [pydoctor](https://bugs.debian.org/807166) (>= 0.5+git20151204)
+* [rpm upstream](https://github.com/rpm-software-management/rpm/pull/144) (>4.13 other relevant patches linked in there)
+* [sphinx](https://github.com/sphinx-doc/sphinx/pull/1954) (>= 1.4, Debian >= 1.3.1-3)
+* [texi2html](https://bugs.debian.org/783475) (Debian >= 1.82+dfsg1-4, [needs forwarding](https://sources.debian.net/src/texi2html/1.82%2Bdfsg1-5/debian/patches/05_reproducible-build/))
+* [texlive-bin](https://bugs.debian.org/792202) (>= 2016.20160512.41045)
+* [txt2man](https://bugs.debian.org/790801) (>= [1.5.7](https://github.com/mvertes/txt2man/pull/1), Debian >= 1.5.6-4)
+* [rcc](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=894476) (Qt5 >= [5.13.0](https://code.qt.io/cgit/qt/qtbase.git/commit/?id=1ffcca4cc208c48ddb06b6a23abf1756f9724351), Debian TODO)
+
+Or you can [search in all Debian sources](https://codesearch.debian.net/search?perpkg=1&q=SOURCE_DATE_EPOCH).
+
+
## More detailed discussion
Sometimes developers of build tools do not want to support `SOURCE_DATE_EPOCH`, or they will tweak the suggestion to something related but different. We really do think the best approach is to use `SOURCE_DATE_EPOCH` exactly as-is described above in our proposal, without any variation. Here we explain our reasoning versus the arguments we have encountered.
=====================================
assets/styles/custom.scss
=====================================
@@ -35,18 +35,25 @@ main {
h1, h2, h3, h4, h5, h6 {
clear: both;
- margin-top: 3rem;
- }
-
- h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
- color: inherit;
+ margin-top: 2rem;
}
h1 {
+ margin-top: 3rem;
font-weight: bold;
margin-bottom: 2.5rem;
}
+ h3 {
+ font-size: 1.5rem;
+ }
+
+
+
+ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
+ color: inherit;
+ }
+
img {
max-width: 100%;
padding-bottom: 0.5rem;
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/de1870906345996ee741879abd367f7eabb473da...3243e14b0cefb99e87253dfe14ba239e4e435074
--
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/de1870906345996ee741879abd367f7eabb473da...3243e14b0cefb99e87253dfe14ba239e4e435074
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.reproducible-builds.org/pipermail/rb-commits/attachments/20240222/8a978ee3/attachment.htm>
More information about the rb-commits
mailing list