Proposal-temporal: What are use cases for DateTime after LocalDateTime lands? (for documentation)

[justingrant]

Once LDT lands, we'll need to explain the difference to users between DateTime and LDT (or whatever their final names end up being). I think a good way to do this in the docs will be to list some example use cases where DateTime is needed and LDT isn't appropriate. Here's an initial draft. What should be added/removed?

• Reading date/time data representing timezone-specific events but where a time zone is not stored with the date/time. In this case, DateTime will usually be used as an intermediate state before converting to LDT or Instant using the missing time zone. Cases where this will happen include:
  
  
  
  • If the time zone is implied by the data, e.g. a company may report all sales data using the time zone of its corporate headquarters.
  
  
  • If the time zone is stored separately, e.g. in a separate database column or user setting
  
  
  • When developers don't realize that the default behavior of the platform they're using (e.g. .NET and most DBMS systems) doesn't store the time zone of the local client when persisting date/time data, and who also didn't follow the best practice of storing UTC timestamps.
  
  
  • When a legacy server app erroneously used a non-UTC system time zone and the app stores all data using server-local time. In this case, data read from those servers must be interpreted in the server's time zone. (Note: the best solution is to fix the server to store all data either in UTC or with an IANA time zone!)
  
  
• As the result of calling a component that is not aware of time zones, e.g. a UI date/time picker.
• Modeling events that happen at the same local time in every time zone. For example, the British Commonwealth observes a two minute silence every November 11th at 11:00AM in local time.
• Reading local date/time data from ISO 8601 strings that have a numeric offset like 2020-04-09T16:08-08:00 or 2010-05-30T08:15+05:30. These strings can also be parsed by Temporal.Absolute, but if you need to know the local date and time then Temporal.DateTime.from is the right API to use. Note: to avoid DST bugs, the result must not be used to create derived values (via arithmetic, with, etc.) unless you are certain that the underlying data was recorded in a time zone that lacks DST and has not had recent changes to its time zone definition.
• Performing arithmetic that expects results only in elapsed clock time and that deliberately ignores the impact of DST. This use comes up rarely, but is needed when displaying clock or calendar UIs. For example: in a day-planner UI, the visual height of a meeting should be calculated using DateTime.prototype.difference of the start and end times, even if some of that clock time is skipped or repeated by DST. Note that this is an unusual case. Most cases _should_ account for DST, e.g. when when displaying the length of a meeting as text e.g. "4 hours" or when calculating the end of a meeting from its start time and duration.

Are there other use cases that the list above omits? We're not looking for convoluted cases where DateTime could be used... but rather what are common use cases where DateTime should be used as a best practice and where LDT isn't appropriate due to bugs, ergonomics, etc.?

Also, what are other examples besides the 4:20 4/20 holiday of a date/time event that should be evaluated the same in every time zone? I thought of a lot of holiday examples (e.g. new year's day) but IMHO those are more properly modeled using a Temporal.Date because they always start at the beginning of the day. What are more examples of intraday events that are the same everywhere?

[gibson042]

Remembrance Day usually includes a two-minute silence at 11:00.

[ryzokuken]

I suppose the discussion could be copied over here from today's notes and this issue be closed?

[ptomato]

@mj1856 mentioned the use case of countries with one time zone and no DST, where DateTime matches the mental model. @pipobscure mentioned that it matches the mental model in other cases as well, when one is planning events for oneself.

[justingrant]

@mj1856 mentioned the use case of countries with one time zone and no DST, where DateTime matches the mental model.

BTW, after thinking more about the single-country/single-timezone/no-DST use case and I think we should NOT recommend DateTime for this use case in the docs. Developers may choose to ignore our guidance and use DateTime anyways--just like they often do with localization advice--but my proposal would be to document a clear standard that recommends that developers who know the place should use LDT, even in cases like India and China.

Why?

• It's a clearer mental model (easier to learn/easier to document) without complex exceptions like "_, except when all stored date/time values are in a single time zone and that time zone has never observed DST for the full range of dates you'll be working with._"
• Code using LDT is easier to localize later, just like it's easier to localize apps that use toLocaleString instead of ${month}/${day}/${year}. For example, imagine a Chinese or Indian app that wants to build a per-user timezone feature to support expats around the world. With LDT, adding such a feature would require replacing a global Asia/Shanghai constant with a per-user variable. With DateTime, the changes would be much harder and error-prone. (FWIW, I'm sensitive to this because my last company had to do an expensive rewrite of "founder code" that was erroneously written to assume a single time zone.)
• Even single-timezone countries can have time zone ambiguity. For example, legal time in China is always Asia/Shanghai, but:

The double time standard is particularly observable in Xinjiang Television, which schedules its Chinese channel according to Beijing Time and its Uyghur and Kazakh channels according to Xinjiang Time.[12] Some ethnic Han population in Xinjiang might not be aware of the existence of the UTC+06:00 Xinjiang Time because of the language barrier.[13]
. . .
In 2014, Apple Inc. released an update to its iOS mobile operating system, which silently changed the default time for users in Xinjiang into Xinjiang Time. As some users in the area were using Beijing Time in their iOS before the update and set the alarm of their phones and tablets according to Beijing Time, the silent change caused some alarms to ring at a time later than expected, causing disruption in daily activity on the day after the changes.[15]

• Even in countries that don't use DST, many of them did use DST relatively recently. For example, China used DST as recently as 1991. For some apps, it may be hard to guarantee in advance that long-past data will never be used.
• It's resilient to future changes in time zone definitions. For example, Samoa's 2011 change to the opposite side of the International Date Line.

Thoughts?

I suppose the discussion could be copied over here from today's notes and this issue be closed?

I'd suggest that we leave it open and close it via a docs PR, perhaps the same PR that resolves #655 via a docs page that maps specific use cases to the right Temporal type for those cases. Until that PR lands, I think this issue could be a helpful honeypot to attract use cases from other commenters.