deobald
commented
5 months ago I've started working on this change and thinking through how we can execute it in a way that both satisfies the requirement and leaves the code readable for future servers.
Regardless of how we choose to implement this feature, I'll reiterate that, once it's built, it will become impossible to diagnose discrepancies between the Perl scripts (email, RSS) and Kosa. The reason for this is that all the Perl script code (and current Kosa/Kosa2 code) is time-dependent, not date-dependent. The crux of all the difficulties highlighted in my previous comment is that times and dates are mathematically impossible to convert and compare. It is counter-intuitive, but a Date and a Time (or DateTime) belong to completely different number systems. The unfortunate truth of this number system incompatibility is that there is no meaning to "today" in Dates, absent a timezone. The concept of "today" only exists in Time.
As long as we remember this, and accept this limitation, the remaining decision is whether we want the new change to be friendlier to users or friendlier to future developers.
Option 1: Friendly to Users
User Outcome: Users see new cards as of 00:00 on "today's" date, in their respective timezone.
Dev Outcome: The API will produce data that is hard to understand. published_date will return tomorrow's date, for most of the world, and published_at will return a time with today as a date component.
How it works: All DateTimes in Kosa2 are normalized to UTC, and will remain so. We would make a singular exception of one timezone-specific scheduled job, set to execute at 00:00 in UTC+12:00 (note: I'll strongly recommend UTC+12:00 instead of UTC+14:00 because the latter puts us two days into the future, which will be even more confusing). This is almost the earliest time, worldwide, and would allow all client phones in the west Pacific to see today's cards at 00:00 in their local time. Data would always look like this, for most of the world, on January 8th:
{ "published_date": "2024-01-08",
"published_at": "2024-01-07T12:00:00Z" }Unless we create a new "version 2" API endpoint, existing mobile app installs will see cards a day early in most of the world, until they update. We can release a "version 2" of the API, if we want.
Option 2: Friendly to Developers
User Outcome: Users see new cards as of 12:00 on "today's" date, in their respective timezone.
Dev Outcome: The API will produce consistent data. published_date will be synchronized with published_at, because everything will operate in UTC.
How it works: All DateTimes in Kosa2 will still be UTC. We wouldn't make any exceptions for schedulers. As a result, the earliest we can run a job is at 00:00 in UTC. This would be at roughly noon (12:00) in the earliest timezone. To remain consistent, worldwide, we would make "today's" cards visible at noon in every timezone. Data would always look like this, for all of the world, on January 8th:
{ "published_date": "2024-01-08",
"published_at": "2024-01-08T00:00:00Z" }This approach still releases cards earlier than Kosa1 currently does in production, since it uses North American times. We could create a new "version 2" API, if we wanted to be pedantic, but this option releases cards "early" at 18:00 CST, which wouldn't be as disruptive if we don't create a v2 API.
Version 2 API
Creating a v2 API before we've even released an official 1.0 version of the software feels... weird... I guess. Doing things like that is usually a good sign we're polishing too much. That said, the software is live (and has been for a while), even if the 1.0 announcement hasn't been made on the mailing list. So perhaps I should think of the Pariyatti app as well into Version 1.0, in which case a corrective v2 API doesn't seem so crazy. Perhaps I'm obsessing over semantics. 😉
Please be aware that there won't be two sets of cards published, so the v1 API would still see cards early... but it would trim "tomorrow's" card from the feed, according to the old Perl/Kosa timezones (or UTC, if we'd prefer that).
Question
I realize neither of these options is ideal. I'm not wedded to either one, but I wanted to hear from you folks if you felt strongly about the various options at play:
- Does anyone feel strongly about "today's" cards being visible at 00:00 vs. 12:00? (I would prefer if we at least kept this to a "round" time, though, and not 05:00 or some other arbitrary number.)
- Does anyone feel strongly about
published_dateandpublished_timein the API being in/out of sync? - Does anyone feel strongly about whether we should create a v1 and v2 API, the first of which will trim "tomorrow's" cards off for European and American users with the old (current) app installed?
Apologies if any of these explanations are confusing! Timezones are the worst. 😆
cc @brihas @balwa @nilendujani
brihas
balwa
After thinking about this for a bit, I realize it does pose some problems:
Assuming we don't bump the Kosa API version (and we shouldn't, for such a small non-breaking change), the Kosa API will serve all the old mobile app installs with the new data. If we release each day's cards as of "the earliest timezone" (UTC+14:00), most mobile app installs will see these cards very early on the previous day. On any given day, old apps will show tomorrow's data under "Today" at these times:
Kosa does not understand the user's timezone (nor should it), and for a wide variety of well-understood reasons, it is not an option to make Kosa's API timezone-aware. This change should exist only in the mobile app itself, since it's exclusively related to the phone or iPad's local timezone, but that means users with old version of the app are going to see weird data.
We probably want to be careful making this change, since it will definitely break old users and the mobile app has no way of requesting the user to upgrade yet.
The other problem I have with this change is that it's quite a divergence from what was requested and built back in January (see: https://github.com/pariyatti/kosa/issues/54). Rather than doing a large amount of work, only to undo or redo it a few months later, I propose we run a prioritization exercise to determine what work will be done on Kosa and the mobile app, how, and in what order.