Notes on handling dates and times

Summary

TL;DR Always use non-naive (time including time zone) datetimes

Things to consider

There are dates and datetimes; they are not the same

  • True dates are pretty rare and are named with _date at the end (birth_date, etc.) They have no time or timezone information
  • Datetimes are pretty common and are named with _at on the end (created_at, etc.) They have time and timezone information. Most datetimes are generated by code, and you do not have to think about them.
  • Nols-api handles any non-naive datetimes and does the time zone conversion if needed. It returns datetimes in UTC. Naive datetimes (no tz info) are not accepted by nols-api.
  • The database stores datetime in US/Mountain, but unless you are dealing directly with the database through SQL you should not care about or accommodate that at all.
  • Some datetimes are populated by naked date instances, meaning there is no known time component; This is either a bug we can do something about (we are truncating the time somewhere upstream in our code) or a bug we have no control over (outside system providing date but no time).
    • If it is something we can fix, we need to fix it.
    • If it is something we cannot fix (or not fix yet), we take the date portion and assign the time of NOON UTC as a marker that we have an intentional "no-time" datetime. There are methods in nols-util to help with this if needed.
  • We should NOT zero out (truncate) the time component, as that creates lots of other issues. It is stored as midnight US/Mountain, which translates to a different date (the previous day) for any place geographically west of the US/Mountain time zone. It also moves around during the year, being either 06:00 UTC or 07:00 UTC depending on the season. Although this has been the historical solution because previously we rarely (if ever) looked at time information, moving forward it is considered a bug.
  • When someone asks you to start mucking with datetime values to make them fit into a report or something similar, this is almost always a bad idea. Translating a bunch of dates to a given timezone is fine: that is presentation logic. Altering some items that enter our system between certain hours of the day is an awful code smell and generally means something else needs fixing.
  • If we get naive datetime values in our system (date and time but no timezone) it is a safe (if icky) assumption it was intended to be the US/Mountain time zone.

From an email titled "Datetimes in our system moving forward" sent to NOLS Software Engineers October 12, 2020