[rb-general] [PATCH] Document timestamp clamping

[Daniel Kahn Gillmor]

On Wed 2016-11-02 16:46:19 -0400, Chris Lamb wrote:
> However, whilst I like the clamp-mtime approach and I also believe it is
> important I strongly think specifications like this should not really
> mention solutions, both in terms of keeping it entirely single-focus,
> avoiding bikeshedding (!), and it also means that that solutions can be
> experimented with and evolved elsewhere with less friction. (eg. on our
> Examples wiki page).

I'm happy to have experiments evolve elsewhere; but those experiments
seem like they've shown that clamping is a necessary part of the
solution to interpreting SOURCE_DATE_EPOCH in a way to facilitate
reproducibility, so we should document the idea at least (even if you
don't want to include the examples) in the specification for how we
expect it to be interpreted.

> I think the "success" of SOURCE_DATE_EPOCH can be somewhat attributed
> to the spec being very easily to follow for the overwhelming majority
> of case.

I think the success can be largely attributed to the excellent work done
by people on this very mailing list ;)  But i agree that the spec has
played a nice role to help that happen.  Adding a clarifying paragraph
about what we've learned about clamping will help anyone in the future
who needs to convince another tool to do clamping.

> Whilst I would totally concede that clamping is not strictly a "solution"
> and there exist examples where it is appropriate to use it over forcing
> stuff (as you list), it's a little too far along the "practical" spectrum
> for me to entirely comfortable with adding this to the spec.

I'm happy to drop the examples if you like, but i think we need to
document the expectation of clamping.  Without it, there are many
specific situations where builds will fail (__TIMESTAMP__ in
auto-generated files and internal tarballs being just two that we have
extensive experience with).

If the counterargument is that clamping shouldn't be necessary because
any tool used during a build must respect SOURCE_DATE_EPOCH absolutely
everywhere, then the implication seems to be that lex, yacc, make, the
shell, automake, tar, etc must all not only inspect their output, but
should also fiddle with the timestamps on files they generate to set
them to SOURCE_DATE_EPOCH.  I think that's even more confusing and
unlikely to expect (and will probably break some timestamp-dependent
tools like make) , so just documenting that clamping is a thing that's
needed in some cases is worthwhile.

As i argue in the patch, setting "current" is actually just a special
case of clamping under common build assumptions.  I don't think we
should re-frame the whole document in terms of clamping, because i agree
with you that the simple explanation of "setting the current time"
should come first so that people get the general idea immediately.

fwiw, i think that examples make a document easier for most people to
grasp, not harder.  I'm happy that they're segregated from the main
spec, though, and that the main spec is an independent read.

What do others think?

      --dkg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 930 bytes
Desc: not available
URL: <http://lists.reproducible-builds.org/pipermail/rb-general/attachments/20161102/2a7f49c9/attachment.sig>