/cc @ianlancetaylor @rsc @robpike

There are no good solutions here but I don't really agree with your proposed docs. As I see it, the time.Time value is not affected by leap seconds at all. The question is how we handle methods like Day and Second and Format, and functions like Parse.

We actually do have leap second information in the zoneinfo files. We could even use it, just as we use the zone offset. We would have to subtract the current leap second offset to gettimeofday when calling time.now. We would change time.abs to consider leap seconds. We would change Format and Parse accordingly. I don't know what the consequences of doing this would be.

Barring that, it seems to me that we should document that when we say UTC we actually mean TAI, and document that time.Now automatically adds the appropriate number of leap seconds.

(To be clear, in issue #15190 you say that there is a problem with time.Sub, but I think the problem is actually with time.Parse.)

Thanks for your comments @ianlancetaylor .

I completely agree with your assessment of where the problem actually lies and how best to fix it. Now() would also have to be updated (and unixToInternal would need to be a function, not a constant etc.)

The tricky thing is how to document current behavior in a way that makes sense. This could be best summarized as "go does it like linux". I've tried my best to do a compact and technically correct summary of this above, but maybe the best thing would be to say "go does it like linux" and link to an off-site URL with the gory details.

I think invoking TAI would actually make it more confusing. TAI is currently 36 seconds offset from UTC. 26 due to leap-seconds and an additional 10 seconds due to epoch differences. It's also an incorrect summary of current behavior, since TAI is a monotonic counting of seconds, and the current behavior uses the POSIX system, which is not strictly monotonic when crossing a leapsecond. However, having said that, using TAI as an internal representation as part of a larger fix seems like a good idea.

The calendrical calculations always assume a Gregorian calendar.

can be changed to say

The calendrical calculations always assume a Gregorian calendar, with no leap seconds.

Decision is what I commented on Apr 12. That's the CL anyone can send.

Done.

CL https://golang.org/cl/30595 mentions this issue.