Clarify that Unix timestamps disregard leap seconds since 1970

[heinrich5991]

Fixes #1626.

Preview: https://pr1627--matrix-spec-previews.netlify.app

[heinrich5991]

Where does the newsfragment go?

None of

appendices
application_service
client_server
identity_service
internal
legacy
push_gateway
room_versions
server_server

seem appropriate.

[richvdh]

good question. @turt2live ?

[richvdh]

I must say, this seems quite a wordy definition. Sometimes, less is more. I'm also not convinced the reference to "Unix timestamps" here is very helpful: fundamentally they aren't unix timestamps, since those are in seconds.

Can we just phrase it as "timestamps are the number of milliseconds elapsed since the unix epoch (1970-01-01 00:00:00 UTC), disregarding leap seconds." ?

[heinrich5991]

Wikipedia seems to be fine with calling them Unix timestamps:

Unix time[a] is a date and time representation widely used in computing. It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch, without adjustments made due to leap seconds. In modern computing, values are sometimes stored with higher granularity, such as microseconds or nanoseconds.

Can we just phrase it as "timestamps are the number of milliseconds elapsed since the unix epoch (1970-01-01 00:00:00 UTC), disregarding leap seconds." ?

I think the way timestamps are defined is very subtle wrt. leap seconds. What does "disregarding leap seconds" mean? Just ignoring them entirely? No, you actively have to know whether you're in a leap second to repeat that second. Of course, since the normal time-related functions on the OSs do that for you, that's easy for the programmer. But I think your sentence is a bit too unclear. The timestamp is absolutely not the number of milliseconds elapsed since the unix epoch, the "disregarding leap seconds" is doing a lot of work there.

[richvdh]

Unix time[a] is a date and time representation widely used in computing. It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch, without adjustments made due to leap seconds. In modern computing, values are sometimes stored with higher granularity, such as microseconds or nanoseconds.

... but that doesn't say that unix timestamps are measured in microseconds or nanoseconds; rather, it says that timestamps may be represented in some other format that has higher granularity. I still don't think it's correct to say "unix timestamps but in milliseconds".

What does "disregarding leap seconds" mean? Just ignoring them entirely? No, you actively have to know whether you're in a leap second to repeat that second.

Well, that's up to you.

I think it's fairly clear what "the number of milliseconds elapsed since the unix epoch ... disregarding leap seconds" means for all times that are not in the middle of a leap second, and I've also said that what happens during a leap second should be left for implementations to decide.

It's interesting to note that the ECMAScript (ie, javascript) spec has a whole section devoted to the subtleties of this ... which makes me wonder if the index should say something short, with a link to a section in the appendices where we can spell out exactly what we mean.

[heinrich5991]

I think it's fairly clear what "the number of milliseconds elapsed since the unix epoch ... disregarding leap seconds" means for all times that are not in the middle of a leap second

I don't think the sentence makes it clear. Maybe we could call it "not counting leap seconds"?

I like the idea of linking to the ECMAScript spec. Is there some kind of link that looks permanent enough to include it in the spec? Is that link already permanent enough?

[richvdh]

I don't think the sentence makes it clear. Maybe we could call it "not counting leap seconds"?

sure.

I like the idea of linking to the ECMAScript spec. Is there some kind of link that looks permanent enough to include it in the spec? Is that link already permanent enough?

Yes I think that link is permanent "enough", but I wouldn't be particularly keen on using the ECMAScript spec as the primary definition. Happy for us to give our own definition and then say "this is the same as the definition in ECMAScript", though.

All I really meant, by reference to the ECMAScript spec, is to note that they give a lot of detail. And I think that, if we wanted to give that much detail, I'd put it in the appendices rather than the index.

[turt2live]

I think this is the first time someone has both read the index and found an issue with it - thank you :)

For now, throw it under appendices I guess. The PR is linked in the rendered changelog so folks can always find the diff that way if they don't spot it in the appendices themselves. Rationale is the index is effectively supplemental information, and would normally be an appendix if we didn't need a landing page.

[richvdh]

please don't force-push after a review, by the way. It makes it harder to see what has changed since the previous review.

[richvdh]

(private DCO signoff has been received from @heinrich5991)

[richvdh]

Thank you!