[Reproducible-commits] [reproducible-website] 15/55: More minor tweaks to improve readability
Chris Lamb
chris at chris-lamb.co.uk
Tue Aug 23 13:39:51 UTC 2016
This is an automated email from the git hooks/post-receive script.
lamby pushed a commit to branch master
in repository reproducible-website.
commit f2bf06f49eaf88af3da2494b4f105072bf0bd144
Author: Paul Gevers <elbrus at debian.org>
Date: Mon Nov 2 16:34:57 2015 +0100
More minor tweaks to improve readability
---
_docs/deterministic_build_systems.md | 2 +-
_docs/locales.md | 15 +++++++--------
_docs/timestamps.md | 32 ++++++++++++++++----------------
_docs/timezones.md | 4 ++--
4 files changed, 26 insertions(+), 27 deletions(-)
diff --git a/_docs/deterministic_build_systems.md b/_docs/deterministic_build_systems.md
index c767b0e..2d811f1 100644
--- a/_docs/deterministic_build_systems.md
+++ b/_docs/deterministic_build_systems.md
@@ -54,5 +54,5 @@ in a build process might require fixes to become non-deterministic. The
Debian effort keep a list of [all issues
found](https://reproducible.debian.net/index_issues.html) while
investigating reproducibility problems in its 22,000+ source packages.
-While some requires changes in the package source itself, some can be
+While some require changes in the package source itself, some can be
fixed by improving or fixing the tools used to perform the builds.
diff --git a/_docs/locales.md b/_docs/locales.md
index 4f775b7..c64a30d 100644
--- a/_docs/locales.md
+++ b/_docs/locales.md
@@ -7,18 +7,17 @@ permalink: /docs/locales/
The locale of the build system might affect the build products. While
it is important that developers have access to error messages in the
language of their choice, tools which output is influenced by the
-current locale can make locale source of reproducibility issues.
+current locale can make locale a source of reproducibility issues.
There are many aspects regarding locales (see [GNU libc locale(1)
-manpage](http://manpages.debian.org/locale)). The ones that follow are those
-who have most often been important to consider in the context of
-reproducible builds.
+manpage](http://manpages.debian.org/locale)). The ones that follow are the
+most important ones to consider in the context of reproducible builds.
Time format
-----------
-Several common time formatting functions will have an output depending
-on the current locale. On POSIX system the formatting will be depend on
+Several common time formatting functions will have output depending
+on the current locale. On POSIX system the formatting will depend on
the `LC_CTIME` environment variable, which can be overriden by
`LC_ALL`.
@@ -83,8 +82,8 @@ LC_ALL=fr_FR lynx -dump -width 72 docs.html | file -
{% endhighlight %}
</div>
-The `C.UTF-8` pseudo-locale always to get the default strings with UTF-8
-output:
+The `C.UTF-8` pseudo-locale can always be used to get the default strings with
+UTF-8 output:
<div class="correct">
{% highlight sh %}
diff --git a/_docs/timestamps.md b/_docs/timestamps.md
index 74e1d6d..ebe86a8 100644
--- a/_docs/timestamps.md
+++ b/_docs/timestamps.md
@@ -14,12 +14,12 @@ software itself…
Timestamps are best avoided
---------------------------
-The time of the build has usually been used as an approximate way
-to know which version of the source has been built, and which tools had
-been used to do it. With reproducible builds, recording the time of the
-build becomes meaningless: on one side, the source code needs to be
-tracked more accurately that just a time, and the build environment
-needs to be defined or extensively recorded.
+Often the time of the build was used as an approximate way to know which
+version of the source has been built, and which tools had been used to do
+it. With reproducible builds, recording the time of the build becomes
+meaningless: on one side, the source code needs to be tracked more accurately
+that just a timestamp, and on the other side, the build environment needs to be
+defined or extensively recorded.
If a date is required to give users an idea on when the software was
made, it is better to use a date that is relevant to the source code
@@ -32,13 +32,13 @@ External tools
--------------
Some tools used in build processes, like code or documentation
-generator, write timestamps which will create unreproducible build
+generators, write timestamps which will create unreproducible build
products.
The Debian reproducible builds effort proposed the
`SOURCE_DATE_EPOCH` environment variable to address the problem. Tools
that support it[^list] will use its value—a number of seconds since January 1st
-1970, 00:00 UTC—when set instead of the current date and time. The
+1970, 00:00 UTC—instead of the current date and time (when set). The
variable has been [formally
defined](https://reproducible-builds.org/specs/source-date-epoch/) in
the hope of wider adoption.
@@ -50,21 +50,21 @@ small and easy to write. Patches for tools which don't yet support the
environment variable have been usually well received and help all users
wanting *reproducible builds*.
-In case where that's not possible, an option is to do post processing on
-the outputs. The idea is either to remove the timestamps entirely or
+In case where that is not possible, an option is to do post-processing on
+the output. The idea is to either remove the timestamps entirely or to
normalize them to a predetermined date and time.
[strip-nondeterminism](https://packages.debian.org/sid/strip-nondeterminism)
-was designed as an extensible program to perform such normalizations on
-a various file formats.
+was designed as an extensible program to perform such normalization on
+various file formats.
Another option is to run these tools using
[libfaketime](http://www.code-wizards.com/projects/libfaketime/).
This library is loaded through the `LD_PRELOAD` environment variable and
-will intercept function calls retrieving the current time of day to
-reply instead a predefined date and time. In some cases, it works
+it will intercept function calls retrieving the current time of day. It will
+reply instead with a predefined date and time. In some cases, it works
just fine and can solve problems without requiring many
changes to a given build system. But if any part of the build process is
-relying on time differences, things will start to go wrong. One case
-of a bad interaction between `libfaketime` and parallel
+relying on time differences, things will go wrong. One case
+of bad interaction between `libfaketime` and parallel
compilation has been identified as a source of [reproducibility issue in
the Tor Browser](https://bugs.torproject.org/12240). So beware.
diff --git a/_docs/timezones.md b/_docs/timezones.md
index f92db49..c07e7cd 100644
--- a/_docs/timezones.md
+++ b/_docs/timezones.md
@@ -60,7 +60,7 @@ specified as UTC.
If time strings without timezone specification are parsed in the
timezone of the build system, hard to understand behavior might happen.
-An example is extra hours when doing time computations across two days
+An example is doing time difference computations in timezones
with different daylight saving changes. As different timezones have
-different policies, one user might get different results depending on
+different policies, a user might get more or less hours depending on
the timezone used to perform the build.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/reproducible-website.git
More information about the Reproducible-commits
mailing list