docs: guide/blog post — RFC 8536 TZif: Why Your Calendar Doesn't Know About the Latest Timezone Change

[allenporter]

Motivation

ical is the only Python iCalendar library that implements RFC 8536 (The Time Zone Information Format / TZif). This is a genuinely unique capability, but nobody knows about it because it's never been explained to developers.

Timezone rules change regularly — countries abolish DST, shift their UTC offset, or split into new timezone regions. When this happens, calendar applications need to know about it. The TZif format (the binary format used by /usr/share/zoneinfo/ on Unix systems and by the tzdata Python package) is how this information is distributed. ical can read these directly.

Developer Pain Points to Address

1. Timezones are not static — Developers assume that "America/New_York" means the same thing forever. It doesn't. Congress could change DST rules (they've tried repeatedly). Countries regularly change their timezone rules:

   • Türkiye abolished DST in 2016
   • Samoa skipped December 30, 2011 entirely when crossing the International Date Line
   • Russia has changed DST policy multiple times
   • Morocco's DST schedule changes frequently based on Ramadan dates

2. VTIMEZONE is supposed to solve this — RFC 5545's VTIMEZONE component embeds the timezone rules directly in the .ics file. But most generators only include the current year's rules, so historical events may display at the wrong time.

3. TZif (RFC 8536) is the authoritative source — The binary timezone files maintained by IANA (and distributed via the tzdata Python package) contain the complete historical and future timezone transition data. ical can read these directly instead of relying solely on VTIMEZONE components.

4. The tzdata package — Python's zoneinfo module uses the system timezone database on Unix, but on Windows (and in some containerized environments) there's no system database. The tzdata package (which ical depends on) provides a cross-platform, pip-installable timezone database that stays current.

Initial Ideas for Exploration

• Open with a real-world scenario: you have a calendar event from 2014 in Moscow. Russia was UTC+4 then but is now UTC+3. Does your calendar show the right time?
• Explain the TZif binary format at a high level — what's in those files in /usr/share/zoneinfo/?
• Show how ical.tzif reads these files and how it integrates with the rest of the library
• Compare: what does icalendar do? (Answer: relies entirely on VTIMEZONE, which may be incomplete)
• Show how to keep timezone data current: pip install --upgrade tzdata
• Explain why ical requires tzdata>=2023.3 as a dependency — this ensures a minimum baseline of timezone data

Publishing

GitHub Pages docs site with cross-posting to dev.to.