Don't Panic — Time, Dates, and Time Zones

Time data is several different things wearing one trench coat. An instant is a point on the shared timeline: excellent for an audit event, log entry, or payment that has already happened. A local date and time is what a calendar and clock showed in a place. They look similar on a screen, which is how the trouble gets in.

UTC gives systems a shared reference, and Z says a timestamp has zero offset from it. An offset such as +02:00 says how one local clock related to UTC at one moment. It does not promise that the same place will use that difference next season. For that, keep an IANA time zone such as Europe/Rome: a named collection of local-time rules, histories, and daylight-saving changes. The calendar has acquired a small bureaucracy. It did not ask permission.

This matters because a future appointment is not an event that has already happened. Store the appointment's local date, local time, and named zone so the intended wall-clock time survives rule changes. Store a completed event as a canonical UTC instant, then derive display time later. Store a birthday or accounting day as a date, not as midnight wandering around in an arbitrary zone looking for an argument.

The surprise is that a local time can be missing or repeated. When clocks move forward, a local time can never occur. When they move backward, the same clock reading can name two instants. An application must reject, ask, or apply a documented policy. Quietly choosing a different meeting time is not a time-zone feature. It is a scheduling bug with good posture.

The Cheatsheet condenses the value types and storage rules. The Slides show the flow from government rule changes through IANA data to a runtime. The Practice Reference uses Python to inspect an instant, a repeated local time, and a skipped one. The Field Notes covers the operational traps that hide behind otherwise tidy timestamp strings. Start there when a value looks perfectly normal and behaves as though it has joined a calendar rebellion.