Skip to content

Commit 1598380

Browse files
authored
#746 Reproducible build source date epoch (#749)
2 parents 3f8d54e + b2df9f8 commit 1598380

6 files changed

Lines changed: 205 additions & 49 deletions

File tree

‎docs/cli.rst‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ the fragments directory if now empty).
5454

5555
The date in `ISO format <https://xkcd.com/1179/>`_ to use in the news file.
5656

57-
Default: today's date
57+
Default: See :ref:`build-timestamp-precedence-order`.
5858

5959
.. option:: --yes
6060

@@ -66,6 +66,38 @@ the fragments directory if now empty).
6666
Don't delete news fragments after the build and don't ask for confirmation whether to delete or keep the fragments.
6767

6868

69+
.. _reproducible-builds:
70+
71+
Reproducible Builds
72+
~~~~~~~~~~~~~~~~~~~
73+
74+
To conform to `Reproducible Builds`_ practices, Towncrier supports the `'SOURCE_DATE_EPOCH' specification`_. Your build procedure can set a static build timestamp in the ``SOURCE_DATE_EPOCH`` environment variable.
75+
76+
.. _Reproducible Builds: https://reproducible-builds.org/
77+
.. _'SOURCE_DATE_EPOCH' specification: https://reproducible-builds.org/specs/source-date-epoch/
78+
79+
The value of ``SOURCE_DATE_EPOCH`` represents the build timestamp as a Unix timestamp (number of seconds since the Unix epoch); the 'date(1)' utility will emit this format on request::
80+
81+
$ export SOURCE_DATE_EPOCH="$( date +'%s' --date='2018-01-01' )"
82+
$ towncrier build
83+
84+
This environment variable will :ref:`override the system clock <build-timestamp-precedence-order>` when computing the build date for the generated document. See the `'SOURCE_DATE_EPOCH' specification`_ for details.
85+
86+
87+
.. _build-timestamp-precedence-order:
88+
89+
Build timestamp precedence order
90+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91+
92+
The build date, used for the generated news document, is computed as the earliest found from this sequence:
93+
94+
* Value of the run-time ``--date`` option.
95+
96+
* Computed from the timestamp value set in :ref:`environment variable 'SOURCE_DATE_EPOCH' <reproducible-builds>`.
97+
98+
* Computed from the system clock value.
99+
100+
69101
``towncrier create``
70102
--------------------
71103

‎docs/tutorial.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,14 @@ You can change this with the ``--date`` flag::
7272

7373
$ towncrier build --date=2018-01-01
7474

75+
To conform to `Reproducible Builds`_ practices, Towncrier also supports the `'SOURCE_DATE_EPOCH' specification`_. See :ref:`reproducible-builds` for more on how this works::
76+
77+
$ export SOURCE_DATE_EPOCH="$( date +'%s' --date='2018-01-01' )"
78+
$ towncrier build
79+
80+
.. _Reproducible Builds: https://reproducible-builds.org/
81+
.. _'SOURCE_DATE_EPOCH' specification: https://reproducible-builds.org/specs/source-date-epoch/
82+
7583

7684
Creating News Fragments
7785
-----------------------

‎src/towncrier/build.py‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,12 @@
77

88
from __future__ import annotations
99

10+
import datetime
1011
import os
1112
import re
1213
import sys
14+
import time
1315

14-
from datetime import date
1516
from pathlib import Path
1617

1718
import click
@@ -32,8 +33,35 @@
3233
from importlib import resources
3334

3435

36+
BUILD_TIME_ENV_VAR_NAME = "SOURCE_DATE_EPOCH"
37+
""" Environment variable name for the build timestamp.
38+
39+
See the Reproducible Builds 'SOURCE_DATE_EPOCH' standard,
40+
<https://reproducible-builds.org/specs/source-date-epoch/>.
41+
"""
42+
43+
ISO_8601_DATE_FORMAT = "%Y-%m-%d"
44+
""" Format string, as used with `strftime`, for ISO 8601 date format. """
45+
46+
3547
def _get_date() -> str:
36-
return date.today().isoformat()
48+
"""Get the “build date” text, respecting reproducible build.
49+
50+
:returns: The text value for the build date, in ISO 8601 format
51+
("%Y-%m-%d").
52+
53+
The `SOURCE_DATE_EPOCH` environment variable, if set, is used as
54+
the build timestamp (and not the system clock), as specified
55+
in <https://reproducible-builds.org/specs/source-date-epoch/>.
56+
57+
If the `SOURCE_DATE_EPOCH` environment variable is not set, the
58+
default is the current system clock time (via `time.time()`).
59+
"""
60+
build_time = time.time()
61+
build_time_unix = int(os.environ.get(BUILD_TIME_ENV_VAR_NAME, build_time))
62+
build_date = datetime.date.fromtimestamp(build_time_unix)
63+
build_date_text = build_date.strftime(ISO_8601_DATE_FORMAT)
64+
return build_date_text
3765

3866

3967
def _validate_answer(ctx: Context, param: Option, value: bool) -> bool:
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
`towncrier build` now support setting the date via the `SOURCE_DATE_EPOCH` specification. This adds support for Reproducible Builds.

‎src/towncrier/test/helpers.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from __future__ import annotations
22

3+
import collections
34
import textwrap
45

56
from functools import wraps
@@ -26,6 +27,38 @@ def write(path: str | Path, contents: str, dedent: bool = False) -> None:
2627
p.write_text(contents)
2728

2829

30+
def write_fake_fragments(
31+
fragments: collections.OrderedDict[(str | Path), str],
32+
) -> None:
33+
"""Write `fragments` as change log entry fragments.
34+
35+
:param fragments: A `collections.OrderedDict` with items
36+
{`file_path`: `fragment_text`}.
37+
"""
38+
for out_path, fragment_text in fragments.items():
39+
write(out_path, fragment_text)
40+
41+
42+
def with_fake_fragments(
43+
fragments: collections.OrderedDict[(str | Path), str],
44+
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
45+
"""Test case decorator to write `fake_fragments` as a fixture.
46+
47+
:param fragments: The fragments to write, as expected by
48+
`write_fake_fragments`.
49+
"""
50+
51+
def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
52+
@wraps(fn)
53+
def test(*args: Any, **kwargs: Any) -> Any:
54+
write_fake_fragments(fragments)
55+
return fn(*args, **kwargs)
56+
57+
return test
58+
59+
return decorator
60+
61+
2962
def read_pkg_resource(path: str) -> str:
3063
"""
3164
Read *path* from the towncrier package.

‎src/towncrier/test/test_build.py‎

Lines changed: 100 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# Copyright (c) Amber Brown, 2015
22
# See LICENSE for details.
33

4+
import collections
5+
import datetime
46
import os
57
import tempfile
68
import textwrap
79

8-
from datetime import date
910
from pathlib import Path
1011
from subprocess import call
1112
from textwrap import dedent
@@ -15,48 +16,64 @@
1516
from twisted.trial.unittest import TestCase
1617

1718
from .._shell import cli
18-
from ..build import _main
19-
from .helpers import read, with_git_project, with_project, write
19+
from ..build import (
20+
BUILD_TIME_ENV_VAR_NAME,
21+
ISO_8601_DATE_FORMAT,
22+
_main,
23+
)
24+
from .helpers import (
25+
read,
26+
with_fake_fragments,
27+
with_git_project,
28+
with_project,
29+
write,
30+
)
31+
32+
33+
_default_fake_fragments = collections.OrderedDict(
34+
[
35+
# Off the shelf news fragment.
36+
("foo/newsfragments/123.feature", "Adds levitation"),
37+
# Towncrier treats this as '124.feature', ignoring '.rst' suffix.
38+
("foo/newsfragments/124.feature.rst", "Extends levitation"),
39+
# Towncrier supports non-numeric news fragment file names.
40+
("foo/newsfragments/baz.feature.rst", "Baz levitation"),
41+
# Towncrier supports file names that have a dot in the name of the
42+
# news fragment
43+
("foo/newsfragments/fix-1.2.feature", "Baz fix levitation"),
44+
# Towncrier supports fragments not linked to a feature.
45+
("foo/newsfragments/+anything.feature", "Orphaned feature"),
46+
("foo/newsfragments/+xxx.feature", "Another orphaned feature"),
47+
(
48+
"foo/newsfragments/+123_orphaned.feature",
49+
"An orphaned feature starting with a number",
50+
),
51+
(
52+
"foo/newsfragments/+12.3_orphaned.feature",
53+
"An orphaned feature starting with a dotted number",
54+
),
55+
(
56+
"foo/newsfragments/+orphaned_123.feature",
57+
"An orphaned feature ending with a number",
58+
),
59+
(
60+
"foo/newsfragments/+orphaned_12.3.feature",
61+
"An orphaned feature ending with a dotted number",
62+
),
63+
# Towncrier ignores file names that don't have a dot.
64+
("foo/newsfragments/README", "Blah blah"),
65+
# And file names that don't have a valid category.
66+
("foo/newsfragments/README.rst", "**Blah blah**"),
67+
],
68+
)
2069

2170

2271
class TestCli(TestCase):
2372
maxDiff = None
2473

2574
@with_project()
75+
@with_fake_fragments(_default_fake_fragments)
2676
def _test_command(self, command, runner):
27-
# Off the shelf newsfragment
28-
with open("foo/newsfragments/123.feature", "w") as f:
29-
f.write("Adds levitation")
30-
# Towncrier treats this as 124.feature, ignoring .rst extension
31-
with open("foo/newsfragments/124.feature.rst", "w") as f:
32-
f.write("Extends levitation")
33-
# Towncrier supports non-numeric newsfragment names.
34-
with open("foo/newsfragments/baz.feature.rst", "w") as f:
35-
f.write("Baz levitation")
36-
# Towncrier supports files that have a dot in the name of the
37-
# newsfragment
38-
with open("foo/newsfragments/fix-1.2.feature", "w") as f:
39-
f.write("Baz fix levitation")
40-
# Towncrier supports fragments not linked to a feature
41-
with open("foo/newsfragments/+anything.feature", "w") as f:
42-
f.write("Orphaned feature")
43-
with open("foo/newsfragments/+xxx.feature", "w") as f:
44-
f.write("Another orphaned feature")
45-
with open("foo/newsfragments/+123_orphaned.feature", "w") as f:
46-
f.write("An orphaned feature starting with a number")
47-
with open("foo/newsfragments/+12.3_orphaned.feature", "w") as f:
48-
f.write("An orphaned feature starting with a dotted number")
49-
with open("foo/newsfragments/+orphaned_123.feature", "w") as f:
50-
f.write("An orphaned feature ending with a number")
51-
with open("foo/newsfragments/+orphaned_12.3.feature", "w") as f:
52-
f.write("An orphaned feature ending with a dotted number")
53-
# Towncrier ignores files that don't have a dot
54-
with open("foo/newsfragments/README", "w") as f:
55-
f.write("Blah blah")
56-
# And files that don't have a valid category
57-
with open("foo/newsfragments/README.rst", "w") as f:
58-
f.write("**Blah blah**")
59-
6077
result = runner.invoke(command, ["--draft", "--date", "01-01-2001"])
6178

6279
self.assertEqual(0, result.exit_code, result.output)
@@ -385,21 +402,58 @@ def run_order_scenario(sections, types):
385402
)
386403

387404
@with_git_project()
388-
def test_draft_no_date(self, runner, commit):
405+
@with_fake_fragments(_default_fake_fragments)
406+
def test_draft_no_date_option_source_date_epoch(self, runner, commit):
389407
"""
390-
If no date is passed, today's date is used.
408+
If no date, and 'SOURCE_DATE_EPOCH' set, use it for build date.
391409
"""
392-
fragment_path1 = "foo/newsfragments/123.feature"
393-
fragment_path2 = "foo/newsfragments/124.feature.rst"
394-
with open(fragment_path1, "w") as f:
395-
f.write("Adds levitation")
396-
with open(fragment_path2, "w") as f:
397-
f.write("Extends levitation")
410+
commit()
398411

412+
fake_clock_datetime = datetime.datetime(
413+
2015,
414+
12,
415+
24,
416+
0,
417+
0,
418+
0,
419+
tzinfo=datetime.timezone.utc,
420+
)
421+
fake_clock_timestamp = int(fake_clock_datetime.timestamp())
422+
fake_clock_timestamp_text = str(fake_clock_timestamp)
423+
fake_os_environ = {
424+
**os.environ,
425+
BUILD_TIME_ENV_VAR_NAME: fake_clock_timestamp_text,
426+
}
427+
with patch("os.environ", fake_os_environ):
428+
result = runner.invoke(_main, ["--draft"])
429+
430+
self.assertEqual(0, result.exit_code)
431+
expected_date = fake_clock_datetime.date()
432+
expected_date_text = expected_date.strftime(ISO_8601_DATE_FORMAT)
433+
self.assertIn(f"Foo 1.2.3 ({expected_date_text})", result.output)
434+
435+
@with_git_project()
436+
@with_fake_fragments(_default_fake_fragments)
437+
def test_draft_no_date_option_no_source_date_epoch(
438+
self,
439+
runner,
440+
commit,
441+
):
442+
"""
443+
If no date option and no 'SOURCE_DATE_EPOCH', should use system clock.
444+
"""
399445
commit()
400446

401-
today = date.today()
402-
result = runner.invoke(_main, ["--draft"])
447+
# Ensure the 'SOURCE_DATE_EPOCH' environment variable is not set.
448+
fake_os_environ = {
449+
key: value
450+
for key, value in os.environ.items()
451+
if (key != BUILD_TIME_ENV_VAR_NAME)
452+
}
453+
454+
today = datetime.date.today()
455+
with patch("os.environ", fake_os_environ):
456+
result = runner.invoke(_main, ["--draft"])
403457

404458
self.assertEqual(0, result.exit_code)
405459
self.assertIn(f"Foo 1.2.3 ({today.isoformat()})", result.output)

0 commit comments

Comments
 (0)