[tahoe-dev] [tahoe-lafs] #1133: don't claim to provide better semantics of timestamps than Python claims to provide

[tahoe-lafs]

#1133: don't claim to provide better semantics of timestamps than Python claims to
provide
---------------------------+------------------------------------------------
 Reporter:  zooko          |           Owner:  somebody 
     Type:  defect         |          Status:  new      
 Priority:  minor          |       Milestone:  undecided
Component:  documentation  |         Version:  1.7.0    
 Keywords:                 |   Launchpad Bug:           
---------------------------+------------------------------------------------
 In [source:docs/frontends/webapi.txt at 4508#L677 webapi.txt] it says:
 {{{
 The timestamps are represented as a number of seconds since the UNIX epoch
 (1970-01-01 00:00:00 UTC), with leap seconds not being counted in the long
 term.
 }}}
 However we get our timestamps from {{{time.time()}}}, which
 [http://docs.python.org/library/time.html#time.time is documented] as:
 {{{
 Return the time as a floating point number expressed in seconds since the
 epoch, in UTC.
 }}}
 If I understand correctly these two specifications are different, because
 UTC includes leap seconds and our docs currently say that leap seconds are
 not counted "in the long term". What does that mean exactly?

 However, this ticket is about documentation and is intended to make this
 particular argument:

 ''argument:'' We should not claim to provide more precise or more correct
 semantics to our users than Python claims to provide to us. (Which
 semantics it in turn gets from {{{gettimeofday()}}} which gets it from
 some combination of linux kernel, libc, local sysadmin policy, ntp server,
 and international telecommunications body politics. I'm not kidding.)


 As far as I understand, the question of how to handle leap seconds is in
 fact left up to the local system administrator. Many but not all system
 administrators then defer to an NTP authority. NTP authorities may or may
 not change their policies about that in the near future--see for example
 this allusion to debates within the ITU-R to change the policy:
 http://www.ucolick.org/~sla/leapsecs/onlinebib.html .

 I think the right thing for our docs to do is to clearly state that the
 precise semantics of this value are unspecified.

-- 
Ticket URL: <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1133>
tahoe-lafs <http://tahoe-lafs.org>
secure decentralized storage