✅

Developer Checklists

Pre-deployment checklists and code review guidelines for time handling. Use these to catch time-related bugs before they reach production.

🚀

Pre-Deployment Checklist

All timestamps stored in UTC

Database columns, API responses, and internal data structures use UTC timestamps

Timezone conversion only for display

Local timezone conversion happens in the presentation layer, not business logic

DST transition testing completed

Tested spring forward (non-existent times) and fall back (ambiguous times) scenarios

Leap year handling verified

February 29th edge cases and leap year arithmetic tested

Timezone database up to date

IANA timezone database is current and deployment process includes updates

Input validation for time data

All user inputs and API endpoints validate date/time formats and ranges

Error handling for invalid times

Graceful handling of non-existent times, invalid dates, and parsing failures

Logging includes timezone information

All log timestamps include timezone info (preferably UTC)

👀

Code Review Checklist

🚨 Red Flags to Watch For

❌

Naive datetime objects

Look for datetime objects without timezone information

datetime.now(), new Date("2024-03-10")
❌

Hardcoded timezone offsets

Avoid fixed offsets that don't account for DST changes

timestamp + (5 * 3600), utc_time - timedelta(hours=8)
❌

Local time arithmetic

Date/time arithmetic performed in local timezone

local_time + timedelta(hours=24)
❌

Ambiguous string parsing

Date strings without explicit format or timezone

Date.parse("01/02/2024"), strptime("2024-03-10 14:30")
❌

Timezone abbreviation usage

Using ambiguous timezone abbreviations instead of IANA names

"EST", "PST", "CST" instead of "America/New_York"

✅ Good Patterns to Look For

✅

Explicit timezone specification

All datetime operations specify timezone explicitly

datetime.now(timezone.utc), DateTime.utc()
✅

UTC for calculations

All date arithmetic performed in UTC

utc_time + timedelta(hours=2)
✅

Safe timezone conversion

Using proper timezone conversion methods

.astimezone(), .setZone(), .withZoneSameInstant()
✅

Input validation

Proper validation of date/time inputs

if (!dt.isValid) throw new Error()
✅

DST-aware testing

Tests cover DST transition edge cases

test_spring_forward(), test_fall_back()
🔌

API Design Checklist

ISO 8601 format for all timestamps

Use standardized format: 2024-03-10T14:30:00.000Z

Always include timezone information

Either UTC (Z suffix) or explicit offset (+05:00)

Accept multiple input formats

Parse ISO 8601, Unix timestamps, and common formats gracefully

Validate timezone names

Accept only valid IANA timezone identifiers

Consistent error responses

Clear error messages for invalid dates, times, and timezones

Version API for timezone changes

Handle timezone database updates without breaking clients

🗄️

Database Design Checklist

All timestamps stored as UTC

Use TIMESTAMP WITH TIME ZONE or equivalent, set to UTC

Separate user timezone preferences

Store user timezone separately from timestamp data

Indexes on timestamp columns

Optimize queries that filter or sort by time

Audit trail with timestamps

created_at, updated_at columns for all important tables

Backup and recovery tested

Verify timestamp integrity across backup/restore operations

🧪

Testing Checklist

Unit Tests

DST spring forward (non-existent times)
DST fall back (ambiguous times)
Leap year February 29th handling
Year 2038 problem (32-bit overflow)
Milliseconds vs seconds confusion
Invalid date/time input handling

Integration Tests

Cross-timezone data consistency
API endpoint timezone handling
Database timestamp storage/retrieval
Scheduled job execution during DST
Multi-timezone user scenarios
📊

Monitoring & Alerting Checklist

DST transition alerts

Monitor system behavior during spring forward and fall back

Timezone database update monitoring

Alert when IANA timezone database needs updating

Clock drift detection

Monitor server time synchronization with NTP

Invalid timestamp error tracking

Monitor and alert on parsing failures and invalid dates

Scheduled job execution monitoring

Verify cron jobs and scheduled tasks run correctly during DST

📋

Quick Reference

Golden Rules

  • • Store everything in UTC
  • • Convert to local time only for display
  • • Never do date arithmetic in local time
  • • Always specify timezone explicitly
  • • Test around DST transitions
  • • Use IANA timezone names, not abbreviations
  • • Validate all time-related inputs
  • • Handle non-existent and ambiguous times

Common Pitfalls

  • • Assuming 24-hour days (DST!)
  • • Mixing seconds and milliseconds
  • • Hardcoding timezone offsets
  • • Using naive datetime objects
  • • Ignoring leap years and leap seconds
  • • Parsing ambiguous date formats
  • • Not testing edge cases
  • • Forgetting timezone database updates