Clarify that Unix timestamps disregard leap seconds since 1970 (#1627)

Fixes #1626.
matrix-org · Aug 24, 2023 · a1b8329 · a1b8329
1 parent ca456a4
commit a1b8329
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 3 deletions.
diff --git a/changelogs/appendices/newsfragments/1627.clarification b/changelogs/appendices/newsfragments/1627.clarification
@@ -0,0 +1 @@
+Clarify timestamp specification with respect to leap seconds.
diff --git a/content/_index.md b/content/_index.md
@@ -419,9 +419,16 @@ into the `m.` namespace.
 
 ### Timestamps
 
-Unless otherwise stated, timestamps are measured as milliseconds since
-the Unix epoch. Throughout the specification this may be referred to as
-POSIX, Unix, or just "time in milliseconds".
+Unless otherwise stated, timestamps are the number of milliseconds
+elapsed since the unix epoch (1970-01-01 00:00:00 UTC), but not counting
+leap seconds, so that each day is precisely 86,400,000 milliseconds.
+
+This means that timestamps can repeat during leap seconds. Most
+programming languages provide timestamps in that format natively, e.g.
+[ECMAScript](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-time-values-and-time-range).
+Throughout the specification this may be referred to as POSIX,
+[Unix](https://en.wikipedia.org/wiki/Unix_time), or just "time in
+milliseconds".
 
 ## Specification Versions