time: Document time.Parse leap second behavior

[williambanfield]

go version: go version go1.17.5 linux/amd64

RFC3339 documents that leap seconds will be denoted as YYYY-MM-DDT23:59:60Z. Attempting to parse such a value using time.Parse returns the following error:

parsing time "2022-12-31T23:59:60Z": second out of range

https://go.dev/play/p/es_oGD37vZl

This behavior seems perfectly reasonable, given the fact that Go's time keeping does not account for the leap second and instead uses the Unix style of time. However, while I notice that the documentation for package time mentions that calendrical calculations always assume a Gregorian calendar, with no leap seconds, it doesn't seem to indicate the parser behavior.

I see that issues have been opened in the past to change the behavior, #8728. This issue is just a request that the behavior be documented as part of the time package.

Happy to provide any other information needed.

[ianlancetaylor]

The time package in general does not know anything about leap seconds. That covers the entire package, including the parsing routines. Personally I think is covered by the general statement of the time package. Is it necessary to repeat that for time.Parse?

In particular, it would be misleadig to parse second 60, because the time package can't represent it. It would be identical to either second 59 or second 0 of the next minute.

[williambanfield]

Personally I think is covered by the general statement of the time package.

I personally took the calendrical calculations always assume a Gregorian calendar, with no leap seconds comment to mean that Add and Sub etc. would not use the leap second when used but I wasn't totally clear on how the parser would handle this and had to do a bit of digging to be sure. Maybe there is another comment that I am missing that clarifies that the whole package is absent any leap second in all places?

In the case that my program encounters an error as a result of trying to read :60 from a different program, it would be nice to have a very obvious place to point operators to to understand what is going on, although, perhaps this exists and I've missed it.

[creachadair]

Per RFC 3339, though, which time.RFC3339 purports to parse, the time-second term is allowed to range over 0–60, and I think Appendix D shows that observing a 60 there at the end of a month or year is equivalent to a normalized time in the next unit (e.g., next month or next year, depending).

I may be misreading it, but I think the parser could actually handle that gracefully.

Edit, to add: I think this could be done without having to address leap-second awareness more generally. This appears to mostly be a syntactic property (e.g., if seconds == 60 and we're at the end of the last day of the month, do a special thing).

[ianlancetaylor]

This appears to mostly be a syntactic property (e.g., if seconds == 60 and we're at the end of the last day of the month, do a special thing).

I don't think that is accurate. A leap second really is an additional second. For cases where leap seconds have been inserted, second 60 really does exist. However, that is only true for time systems that understand leap seconds. The time package is not such a system. The time package has no way to represent the fact that some minutes are 61 seconds long. If we accepted second 60 in time.Parse, we would be accepting information that we would have to discard. That doesn't seem like the best approach.