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?

• Representing timezone-specific events where the time zone is not stored together with the date/time data. In this case, Temporal.PlainDateTime will often be used as an intermediate step before converting to/from Temporal.ZonedDateTime or Temporal.Instant using the separate time zone. Examples:
  • When the time zone is stored separately, e.g. in a separate database column or a per-user setting
  • When the time zone is implicit in the data, e.g. stock exchange data that is always in America/New_York time zone, or a legacy system that always records date/time data in the server's time zone.
• When passing data to/from a component that is unaware 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.
• When local date/time matters but time zone is irrelevant, e.g. a sleep tracking device that only cares about the local time you went to sleep and woke up, regardless of where in the world you are.
• Reading local time from ISO 8601 strings like 2020-04-09T16:08-08:00 that have a numeric offset instead of an IANA time zone like America/Los_Angeles. 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 required. To avoid DST bugs, the result must be converted to a real time zone before creating derived values via add, with, etc.
• Performing arithmetic that deliberately ignores the impact of DST. Example: in a day-planner UI, the visual height of a meeting may be the same even if DST skips or repeats an hour.

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.

[justingrant]

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.

I think it's been open long enough to attract use cases, so I PR-ed some brief use cases into the PDT docs in #1344.