Warnings about time shifts

[dcastro]

Clarification and motivation

When a user writes a message with an invalid/ambiguous time reference, we emit the warnings below. However, these messages could be a bit more helpful, and are sometimes even misleading.

---

"01:30am in America/Winnipeg on 5th november"
ambiguous because of the time shift

There is a timeshift in America/Winnipeg around the specified time and this particular timestamp can be possible with different offsets, please define the offset explicitly.

• "please define the offset explicitly" We know exactly which offsets are possible, the TZError.TZOVerlap constructor contains this information. We should tell the user something more specific so that they'll know how to fix their message.

Suggestion:

"01:30am in America/Winnipeg on 5th november"
Ambiguous time

The clocks are turned backward <x> hour(s) (and <y> minute(s)) in America/Winnipeg around the specified time and this particular time occurs twice.
Please edit your message or write a new one and specify one of the following offsets: UTC-05:00 or UTC-06:00.

---

"02:30am in America/Winnipeg on 12th march"
invalid because of the time shift

There is a timeshift in America/Winnipeg around the specified time and this particular timestamp does not exist, please define the offset explicitly.

• "timeshift" vs "time shift": we should use consistent spelling.

• "please define the offset explicitly" Defining the offset explicitly would not help. The time simply does not occur.

• We could use the times given by the TZError.TZGap constructor as suggestion for how to fix the problem. In this example, the constructor will return the given time (02:30) shifted backward and forward by the duration (1 hour) of the gap, i.e. 01:30 and 03:30.

Suggestion:

"02:30am in America/Winnipeg on 12th march"
Invalid time

The clocks are turned forward <x> hour(s) (and <y> minute(s)) in America/Winnipeg around the specified time and this particular time does not occur.
Please edit your message or write a new one and amend the time. Did you mean 01:30 or 03:30 instead?

Acceptance criteria

• The "ambiguous" warning tells users which offsets are possible
• The "invalid" warning does not tell users to specify an offset, as that wouldn't help
• The "invalid" warning suggests some possible valid times to the user

[YuriRomanowski]

I mostly like your proposal regarding overlapping. However, there are some points about time gaps I would argue:

"please define the offset explicitly" Defining the offset explicitly would not help. The time simply does not occur.

If the user defines an offset explicitly, every time will be valid, times can be invalid only in timezones (which assume timeshifts).

We could use the times given by the TZError.TZGap constructor as suggestion for how to fix the problem. In this example, the constructor will return the given time (02:30) shifted backward and forward by the duration (1 hour) of the gap, i.e. 01:30 and 03:30.

Also, I don't think that suggesting 1:30 or 3:30 will make sense for the user if he mentioned 2:30. I'd rather return an interval of local times that are not valid, i.e. from 2am to 3am, such that he knew what times he can use.

That said, I'd suggest to either select any time outside of "broken" interval, or specify an offset explicitly. In fact, I think that my most natural reaction to that error message would be just to specify a timestamp in UTC. Hence, my proposal looks like this (please fix me if my English is wrong :smile:):

"02:30am in America/Winnipeg on 12th march"
Invalid time

The clocks are turned forward <x> hour(s) (and <y> minute(s)) in America/Winnipeg around the specified time and this particular time does not occur.
Please edit your message or write a new one and amend the time. You can use any time outside of 02:00-03:00am interval, or define an offset explicitly.

[dcastro]

If the user defines an offset explicitly, every time will be valid, times can be invalid only in timezones (which assume timeshifts).

Well, yes, good point, that's true, but that's probably not the right way to fix the user's issue (I'll elaborate on why in the comment below)

Also, I don't think that suggesting 1:30 or 3:30 will make sense for the user if he mentioned 2:30

If I say "let's meet tomorrow at 2:30pm" and, tomorrow, the clocks on my timezone go forwards from 2pm to 3pm and an hour is skipped, then I probably just want to correct my message to say "let's meet tomorrow at 3:30pm". I don't think telling me to specify an offset would be very helpful, I don't even know which offset to use, I'd have to do a bit of math in my head first - and that's exactly what I want the bot to do for me.

In fact, I think that my most natural reaction to that error message would be just to specify a timestamp in UTC.

Same as above. I mean, we are kinda used to dealing with timezone conversions and can quickly map our local time to an UTC time without much mental effort (it's especially easy for me, because my time zone observes GMT+1 during summer and GMT+0 otherwise :sweat_smile:).

But it's probably not so easy for most people. Especially while a time zone is transitioning from one offset to another, telling the user to pick an offset may be confusing. As I said, as a user, this is the kind of thing I want the bot to do for me.

I'd rather return an interval of local times that are not valid, i.e. from 2am to 3am, such that he knew what times he can use.

That information could be very useful, yes. I haven't looked too much into it, but is easy to find the exact boundaries of the time gap (with the tz/tztime/whatever APIs we have available)?

If it's easy enough to do, I would suggest incorporating that into my initial proposal, e.g.:

"02:30am in America/Winnipeg on 12th march"
Invalid time

At 02:00, the clocks are turned forward <x> hour(s) (and <y> minute(s)) to 03:00 and this particular time does not occur in America/Winnipeg.
Please edit your message or write a new one and amend the time. Did you mean 01:30 or 03:30 instead?

[YuriRomanowski]

That information could be very useful, yes. I haven't looked too much into it, but is easy to find the exact boundaries of the time gap (with the tz/tztime/whatever APIs we have available)?

I guess we'll need to go into tz internals, like I did here.