[rb-general] [PATCH] Document timestamp clamping

[Daniel Kahn Gillmor]

The current spec talks only about "current" time, but doesn't mention
"clamping".  We've found that "clamping" is an important concept (see
the attached examples) in practice, so it should be included in the
spec.
---
 source-date-epoch-spec.xml | 63 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/source-date-epoch-spec.xml b/source-date-epoch-spec.xml
index 054acf7..772f5fe 100644
--- a/source-date-epoch-spec.xml
+++ b/source-date-epoch-spec.xml
@@ -140,6 +140,16 @@
 			time.
 		</para>
 		<para>
+			Where build processes embed timestamps that are not
+			"current", but are somehow related to the source and
+			the build processes, they MUST use a timestamp no later
+			than <envar>SOURCE_DATE_EPOCH</envar>.  That is, such
+			values should be "clamped" to
+			<envar>SOURCE_DATE_EPOCH</envar> so that they don't
+			appear to be "from the future".  See the "Timestamp
+			Clamping" section below.
+		</para>
+		<para>
 			Build systems MUST NOT overwrite this variable for
 			child processes to consume if it is already present.
 		</para>
@@ -157,10 +167,52 @@
 
 <sect1>
 	<title>Examples</title>
-	<para>
-		Examples are available at <ulink
-		url="https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal#Examples">https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal#Examples</ulink>.
-	</para>
+	<sect2>
+		<title>Timestamp clamping</title>
+		<para>
+			We generally assume that a build is taking place after
+			the time designated by
+			<envar>SOURCE_DATE_EPOCH</envar>.  This means that we
+			want the build process treat any references to
+			timestamps that happen to be created during the build
+			as though they happened at
+			<envar>SOURCE_DATE_EPOCH</envar>, while we want to
+			leave any other timestamps untouched.
+		</para>
+		<para>
+			For example, the C macro
+			<computeroutput>__TIMESTAMP__</computeroutput> should
+			be "clamped".  That means an intermediate C source file
+			generated during a build which includes a
+			<computeroutput>__TIMESTAMP__</computeroutput> macro
+			would use <envar>SOURCE_DATE_EPOCH</envar>, while an
+			actual file from the source tree would resolve the
+			macro to its stable, pre-existing timestamp.
+          </para>
+          <para>
+			If a build process includes the creation of a tarball,
+			it may include both untouched upstream source and
+			generated files.  Some variants of
+			<command>tar</command> support a
+			<command>--clamp-mtime</command> option that can be
+			used to ensure that the tarball's timestamps of the
+			generated files do not exceed the
+			<envar>SOURCE_DATE_EPOCH</envar>.
+		</para>
+		<para>
+			Note that fixing the "current" time to
+			<envar>SOURCE_DATE_EPOCH</envar> is in some sense a
+			special case of this "clamping", since the build is
+			never done in the past.
+		</para>
+	</sect2>
+	<sect2>
+		<title>Other examples</title>
+		<para>
+			Other examples are available at <ulink
+			url="https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal#Examples">https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal#Examples</ulink>.
+		</para>
+	</sect2>
 </sect1>
 
 <sect1>
@@ -208,6 +260,9 @@
 		Chris West (Faux)
 	</para></listitem>
 	<listitem><para>
+		Daniel Kahn Gillmor (dkg)
+	</para></listitem>
+	<listitem><para>
 		Dmitry Shachnev
 	</para></listitem>
 	<listitem><para>
-- 
2.10.1