Add admonition about Date functions now using UTC

[thadguidry]

• Fixes Fix date parsing regression introduced in 2018 OpenRefine#6009

[netlify]

✅ Deploy Preview for openrefine-website ready!

Name	Link
🔨 Latest commit	09cea0c
🔍 Latest deploy log	https://app.netlify.com/sites/openrefine-website/deploys/66c3de0946571d0008439ca6
😎 Deploy Preview	https://deploy-preview-360--openrefine-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[thadguidry]

@tfmorris and @ostephens Do you think this would close that linked issue?

[tfmorris]

Thanks for tackling this! I was hoping someone was going to address documenting the incompatible changes.

I think the description needs fleshing out a little bit with a general discussion of the change and compatibility implications, as well as specific references near the affected functions (mostly toDate() and toString(), I think).

The current proposal only mentions benefits without any drawbacks. Is that intentional? It seems to me to leave out half the story.

[tfmorris]

The most relevant place for this information is with the toDate() and toString() documentation, although those should probably be brief references to a more general discussion.

[thadguidry]

I wanted to have this generally at the beginning of discussing all the Date functions.
But would love your help on the toString() documentation suggestions which I can add in this PR.

[tfmorris]

Not related to this PR, but since it caught my eye, ISO 8601 isn't involved. Although this does the same thing as before, due to the changes in toString(), the effective date/time is different.

[thadguidry]

I don't quite understand. This is the now() function directly, which returns a date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, according to the Java docs. So I think this reads OK as is? But I think your point is that we need to improve the toString() documentation more fully? I can do that in this PR also.

[thadguidry]

Actually, that's wrong... now() will always return the date-time from the users system clock in the specified time-zone (which is Z according to our code , which means Zulu time, which means we return the users system time without any offset.)

So should now() docs stay as is, because it does return the users system clock in ISO 8601 format?

[tfmorris]

It's only semantics, but the date handling is complicated enough without leading people astray. ISO 8601 dates are represented using strings. What the now() function returns is an internal OpenRefine datetime object. The square brackets around "[date 2020-11-26T15:53:00Z]" and the leading "date" prefix indicate that this is the default toString() rendering for an internal date object, not a string. The expression now().toString() would give "2020-11-26T15:53:00Z" for the above example. Using OpenRefine 2.8, now()returns a date object rendered as "[date 2024-08-20T17:16:42Z]" whilenow().toString()` returns "Aug 20, 2024" using my default system locale and now().toString("hh:mm a z") return "05:20 PM EDT" which matches the current local wall clock time.

In addition to date to string conversions, import/export from spreadsheet formats like Excel and OpenOffice behave differently as well.

[thadguidry]

Wait, so you want to document that OpenRefine prior to 3.0 handled this differently? If that is your concern, I think it's less important how prior 3.0 handled things and just document how they currently work over the last few versions. Our surveys show that everyone is using at least OpenRefine 3.7+ ?

[tfmorris]

The whole point of #6009 is documenting (instead of fixing) the date handling regression. If that's not what this is addressing, you should remove the tag.

The discussion of now() is separate. It doesn't return an ISO 8601 formatted string. It returns a datetime.

I'll let you and @ostephens decide how you're going to document this. My preference was to fix the bugs, but I got overruled.

[thadguidry]

@tfmorris Can you express how you would word things?

I think the description needs fleshing out a little bit with a general discussion of the change and compatibility implications, as well as specific references near the affected functions (mostly toDate() and toString(), I think).