notifications-api/docs/adrs/0002-how-to-handle-timezones.md

TITLE: Determine How to Handle Timezones in US Notify

CREATED DATE	LAST UPDATED	STATUS	AUTHOR	STAKEHOLDERS
06/06/2023	06/15/2023	Accepted	@terrazoon, @ccostino	@GSA/notify-contributors

CONTEXT AND PROBLEM STATEMENT

OPEN ISSUE(S): https://github.com/GSA/notifications-api/issues/260, along with a related pull request: https://github.com/GSA/notifications-api/pull/272

Currently, the application converts back and forth to Eastern Time in a few places, using utilities provided by notifications-utils. This adds complexity and possible confusion since we'll actually be working over multiple timezones.

We are currently linked to timezones in the backend, and we want to unlink it, but we quickly find places where things do not match up.

DECISION DRIVERS

We're looking for these primary outcomes with this work:

• Find all the time-dependent pieces of the application.
• Decide what we can tackle now versus later.
• Determine what the return on this is.

We've also identified the following areas as pieces of the application and service that could be impacted by any timezone changes:

• Reports by day (or specific month/year)
• Jobs running at a reasonable time
• Job schedules (we want users to understand when things will happen)
• Scheduling sending of messages
• UI listing of time messages were sent

Ultimately, we're looking for the least disruption possible while maximimizing our ability to operate the service consistently with predictable results.

SECURITY COMPLIANCE CONSIDERATIONS

None at this time, given that the nature of this work is strictly changing the way timezones are handled in the existing application.

CONSIDERED OPTIONS

As a team, we've gone through the following options:

• Backend UTC, frontend explicitly ET: We convert the backend to UTC and keep the frontend as Eastern Time.

• Backend UTC, frontend UTC: We convert both the backend and frontend to UTC time.

• Backend UTC, frontend configurable at service level: We convert the backend to UTC and make the frontend configurable at the eservice level.

• Backend UTC, frontend configurable at user level: We convert the backend to UTC and make the frontend configurable at the user level.

• Backend UTC, frontend verbose (various options): We convert the backend to UTC and strive for maximum flexibility on the frontend with a variety of configuration options.

For all of these options, we've settled on the need to adjust the backend service to operate and manage timezones with UTC only.

Pros of converting the backend to UTC:

• Eliminates entire classes of bugs trying to synchronize jobs, reports, scheduling of sending messages, etc., and ensures things are always running when expected.

• This is a fairly standard industry practice when dealing with any timezone management in the applicationo; have the backend operate strictly with UTC and leave the display and formatting of timezones in local time to the client.

Cons of converting the backend to UTC:

• There's a decent amount of work involved in the conversation, and tests need to be updated to ensure they're accounting for the timezone change as well.

For the frontend choices we have, it comes down to level of effort, time involved, and what is a higher priority for us now versus later.

Pros of converting parts of the frontend now:

• It provides a bit of consistency with the backend change, and accounts for the work now instead of later.

• It offers a level of configuration not currently available in the app, which would allow users to interact with and customize it in ways that better suite their needs and preferences.

Cons of converting parts of the frontend now:

• There is a lot of additional work involved, not all touch points are known, and there is a signficant effort underway at the moment to update the frontend design and information architecture.

• We're still not entirely sure at which level of granularity we'd like to offer customization, if any.

CHOSEN OPTION: Backend UTC, frontend UTC

After talking through each of these options together as a team, we have decided to move forward with converting the backend to UTC fully and pairing that work with displaying UTC in the frontend where need be.

@terrazoon had an open PR with most of the work already accounted for, and explained the rationale for making the change based on previous work and project experience.

Multiple team members also spoke about the benefits of storing, processing, and managaging timezones as only UTC in the backend of the system and that it's worth the additional work to implement. The challenges inherent in trying to manage timezones directly are too many and greatly increase the risk of new bugs and undesired behavior and side-effects being introduced into the system.

Consequences

• Positive

  • Work was already partially complete for the backend adjustment.
  • Consistent handling of timezones with just UTC across the system in the backend.
  • Provides support to adjust the frontend and other clients as desired going forward.

• Negative

  • The additional work includes updating tests to make sure they all continue to work properly.
  • User testing will also have to be conducted to account for both the app still functioning properly and noting where in the UI/frontend things will need to change.

VALIDATION AND NEXT STEPS

With the decision to move the backend to UTC, the following actions need to be taken:

• Change the backend to use UTC: Remove all references to specific timezones and switch everything to use UTC.

  • Accounted for in https://github.com/GSA/notifications-api/pull/272

• Update tests to account for the UTC change: All of the tests that have anything to do with a timezone will need to be updated to continue to work properly.

  • Accounted for in https://github.com/GSA/notifications-api/pull/272

We also need to update the frontend to account for these changes. This will be done in two parts:

1. We'll update the UI to make sure everything reflects UTC where necessary for any timzone displays. This work will be tracked in this issue: https://github.com/GSA/notifications-admin/issues/525

2. We need to create an ADR for future frontend work for how we'd like to handle timezones in the UI going forward. This is currently noted in this issue: https://github.com/GSA/notifications-api/issues/286