[time] Mark posix_tz parser as bridge code to remove before 2026.9.0

The C++ POSIX TZ string parser is only needed for backward compatibility
with older Home Assistant clients that send the timezone as a string.
Once all clients send the pre-parsed ParsedTimezone protobuf struct,
the parser and its helpers can be removed entirely.

See https://github.com/esphome/backlog/issues/91

esphome/components/time/posix_tz.cpp

@@ -17,7 +17,8 @@ const ParsedTimezone &get_global_tz() { return global_tz_; }
 
 namespace internal {
 
-// Helper to parse an unsigned integer from string, updating pointer
+// Remove before 2026.9.0: parse_uint, skip_tz_name, parse_offset, parse_dst_rule,
+// and parse_transition_time are only used by parse_posix_tz() (bridge code).
 static uint32_t parse_uint(const char *&p) {
   uint32_t value = 0;
   while (std::isdigit(static_cast<unsigned char>(*p))) {
@@ -364,6 +365,12 @@ bool __attribute__((noinline)) is_in_dst(time_t utc_epoch, const ParsedTimezone
   }
 }
 
+// Remove before 2026.9.0: This parser is bridge code for backward compatibility with
+// older Home Assistant clients that send the timezone as a POSIX TZ string instead of
+// the pre-parsed ParsedTimezone protobuf struct. Once all clients send the struct
+// directly, this function and the parsing helpers above (skip_tz_name, parse_offset,
+// parse_dst_rule, parse_transition_time) can be removed.
+// See https://github.com/esphome/backlog/issues/91
 bool parse_posix_tz(const char *tz_string, ParsedTimezone &result) {
   if (!tz_string || !*tz_string) {
     return false;

esphome/components/time/posix_tz.h

@@ -37,6 +37,14 @@ struct ParsedTimezone {
 };
 
 /// Parse a POSIX TZ string into a ParsedTimezone struct.
+///
+/// @deprecated Remove before 2026.9.0 (bridge code for backward compatibility).
+/// This parser only exists so that older Home Assistant clients that send the timezone
+/// as a string (instead of the pre-parsed ParsedTimezone protobuf struct) can still
+/// set the timezone on the device. Once all clients are updated to send the struct
+/// directly, this function and all internal parsing helpers will be removed.
+/// See https://github.com/esphome/backlog/issues/91
+///
 /// Supports formats like:
 ///   - "EST5" (simple offset, no DST)
 ///   - "EST5EDT,M3.2.0,M11.1.0" (with DST, M-format rules)
@@ -72,7 +80,11 @@ const ParsedTimezone &get_global_tz();
 /// @return true if DST is in effect at the given time
 bool is_in_dst(time_t utc_epoch, const ParsedTimezone &tz);
 
-// Internal helper functions exposed for testing
+// Internal helper functions exposed for testing.
+// Remove before 2026.9.0: skip_tz_name, parse_offset, parse_dst_rule are only
+// used by parse_posix_tz() which is bridge code for backward compatibility.
+// The remaining helpers (epoch_to_tm_utc, day_of_week, days_in_month, etc.)
+// are used by the conversion functions and will stay.
 
 namespace internal {