How Can You Document Local Time Behavior?
From the earlier reference collection. Read the current software blog.
Explain which clock a timestamp uses, how daylight-saving transitions affect it, and how overnight schedules are represented.
Name the clock behind each timestamp
A timestamp is incomplete when a reader cannot tell which clock it follows. State the time zone by a clear name, such as America/Los_Angeles, and say whether displayed values are local wall time or UTC. Avoid relying on labels like “local” alone: a reader may be elsewhere, and a server may run in a different zone from its users. If one screen combines values from multiple places, identify the zone beside each location or provide a consistent conversion rule.
For example, a data row might show “2026-11-02 08:30 America/Los_Angeles.” If an API stores UTC but the page displays local time, document both representations and explain which one controls sorting and filtering. Include the format, such as an ISO-style timestamp with an offset, and explain whether seconds are included. This helps someone compare an exported record with what appeared on screen.
Explain the repeated and missing hour
In regions that observe daylight saving, clocks move forward in spring and backward in autumn. The forward change can make a local clock time nonexistent; the backward change can make one occur twice. Documentation should say how the application handles those cases. Does it reject an ambiguous entry, choose the earlier offset, or require the user to specify an offset? Describe actual behavior rather than assuming every reader knows the convention.
A worked example makes the distinction clear: if clocks move from 01:59 to 03:00, a request for 02:30 has no matching local instant. When clocks repeat 01:00 through 01:59, “01:30” alone cannot select one of the two instants. If the system does not accept user-entered local timestamps, say so and explain how conversion is done.
Describe overnight service days
Schedules sometimes use a service day that continues past midnight. A trip shown as 25:15 may mean 01:15 on the following calendar date while remaining part of the prior service day. State whether your product uses this convention, the maximum supported hour range, and how a date filter relates to the service day. Transit schedules are a familiar example: the GTFS reference defines service-day concepts and notes that times can extend beyond 24:00:00. A project using that format should link the precise reference revision it follows.
Give a concrete sample: Friday service at 24:30 corresponds to half past midnight on Saturday, but belongs to Friday's service schedule. Clarify which date is used in exports and user-facing labels.
Put the rule next to the data
A useful time note identifies the zone, format, transition behavior, and overnight rule in one place, then repeats a short label near charts and downloads. If behavior differs between an API and a display, document each separately. Include a sample record that readers can compare with their own output, and say what happens when the zone database changes or a location lacks daylight-saving adjustments.
End with the practical consequence: readers can decide whether two timestamps refer to the same instant and whether a late-night event belongs to the date shown. If the system's behavior has not been checked for a transition case, mark that case as unverified instead of implying a guarantee.