Editorial: simplify and clarify time zone identifier spec text

[justingrant]

This PR simplifies and clarifies spec text related to time zone identifiers, but is not intended to change any observable behavior nor implementer requirements.

Goals of this PR include to make it easier to later integrate Temporal into ECMA-262, to simplify both Temporal and ECMA-402 spec text by centralizing common logic in ECMA-262, and to make it less disruptive to make future normative changes to time zone identifier behavior.

If this PR is merged into ECMA-262, editorial PRs will follow for Temporal (draft: tc39/proposal-temporal#2573) and ECMA-402 (draft TBD) to leverage the updated spec text and AOs to simplify those specs.

Changes:

• Adds editorial spec text explaining how time zone identifiers work in ECMAScript, and pointing readers to 402 for implementations that use the IANA TimeZoneDatabase.
• Adds definitions related to time zone identifiers.
• Renames DefaultTimeZone to SystemTimeZoneIdentifier in order to more clearly match its intent.
• Removes the need to override SystemTimeZoneIdentifier in ECMA-402.
• Renames variables named timeZone to timeZoneIdentifier to avoid future ambiguity with Temporal.TimeZone.
• Adds text that more clearly explains existing spec text allowing non-402 implementations to support non-UTC time zones.
• Adds new abstract operation AvailableNamedTimeZoneIdentifiers which, along with the existing (renamed to) SystemTimeZoneIdentifier, enables all ECMA-402 and Temporal operations related to time zone identifiers to be implemented on top of these AOs.

EDIT: Other editorial changes that were originally in this PR have been moved into Temporal and will be merged along with Temporal later, either into 262 or 402.

cc @gibson042

[justingrant]

Sorry for the flurry of commit spam to fix formatting and typecheck complaints. Also rebased to main while I was in the neighborhood. Should be ready for review now.

[justingrant]

Thanks @bakkot for the review! I think I've resolved the concerns you raised, but let me know if you'd like to see more changes. Thanks again.

[gibson042]

I'm pretty sure HostTimeZoneIdentifier should be added to the list in D.1, and probably also AvailableTimeZoneIdentifiers.

[justingrant]

@gibson042 Thanks for the review! All your suggestions are included in the latest commit.

I'm pretty sure HostTimeZoneIdentifier should be added to the list in D.1, and probably also AvailableTimeZoneIdentifiers.

I added HostTimeZoneIdentifier to D.1 (and changed its type to host-defined AO).

AvailableTimeZoneIdentifiers, as implemented today in all major implementations, is not host-dependent. The list of identifiers and their rules are baked into each implementation and are the same for every host running the same version of the implementation. So I left AvailableTimeZoneIdentifiers as implementation-defined, not host-defined.

Holler if that's a problem.

Otherwise I think I've resolved all open issues reported by all reviewers so far.

[justingrant]

Hi All - I believe that all review comments have been addressed, and I just rebased to main. Let me know if there's any more changes needed. Thanks!

[gibson042]

AvailableTimeZoneIdentifiers, as implemented today in all major implementations, is not host-dependent. The list of identifiers and their rules are baked into each implementation and are the same for every host running the same version of the implementation. So I left AvailableTimeZoneIdentifiers as implementation-defined, not host-defined.

In ECMA-262, "host" refers not to an operating system but rather to consumers of the spec that define a specific subset of implementation-defined operations (e.g., HTML is such a host). So I suppose my original suggestion was in error and Annex D should not be changed, since we don't expect HTML or other specifications to define HostTimeZoneIdentifier or AvailableTimeZoneIdentifiers. I apologize for the churn.

[syg]

We discussed this in the editor call, and our thoughts are:

• We'd like to minimize complexity related to TZDB and IANA in 262. The current 262 editor group, and future ones, are likely to continue not having the needed expertise, so having more complexity than needed in 262 risks bitrot in the future.
• We're sympathetic with the motivation to make the 402/262 layering more intentional than ad hoc overriding of AOs. Is there a middle ground for this PR where we add intentional override points for 402 but leave the complexity in 402? (Those override points aren't going to be host hooks though, see below.)
• HostTimeZoneIdentifier shouldn't be a host hook. 402 isn't really a host. It's probably implementation-defined though.

For now we're not requesting any additional work to be done on this PR. Please stay tuned while we chat and review this more.

[justingrant]

• HostTimeZoneIdentifier shouldn't be a host hook. 402 isn't really a host. It's probably implementation-defined though.

Yep, agreed. I changed it to a host hook in response to @gibson042's review, but per his later comment (and your note too), I'll plan to remove the line in Annex D and revert HostTimeZoneIdentifier back to implementation-defined.

Should we also rename it to something not Host*? If so, what's the typical 262 wording for "dynamic info from the environment" ? SystemTimeZoneIdentifier? UserTimeZoneidentifier? AgentTimeZoneIdentifier? Something else? I'm OK with any name that doesn't include "default".

• We're sympathetic with the motivation to make the 402/262 layering more intentional than ad hoc overriding of AOs. Is there a middle ground for this PR where we add intentional override points for 402 but leave the complexity in 402?

Great question. The main challenge is that it was decided (@gibson042 or @ptomato should know the history) that an ECMAScript implementation can support IANA time zones without supporting all of 402. I believe this was for systems that need time-zone-aware arithmetic but don't need localized formatting for end users. Presumably the 262 spec should give implementers guidance for that case.

Here's three possible options to do that:

• Option 1 - Leave all text in 262 from this PR but acknowledge that TG2 folks will need to watch out for bit rot, which they'll have to anyways because all 402 time zone logic will depend on the 262 text and AOs. Essentially TG1 would sublet the identifier parts of the spec to TG2, but would leave the text in 262 to keep things simpler for implementers.
• Option 2 - Share the shape of all AOs between 262 and 402. Limit the 262 text to generic and/or UTC-only time zone info. Link to 402 whenever 262 mentions IANA or non-UTC zones. Details:
  • Shrink the #sec-time-zone-identifiers section in this PR to mostly definitions (like "primary time zone identifier"), and move the rest of that section into a new 402 section to discuss TZDB specifics: build options, updating TZDB, canonicalization footguns, etc.
  • Anywhere in 262 we mention IANA, link to the 402 section above with a standard note, something like this: "An implementation that supports time zones other than UTC is recommended to follow the requirements described in [link to 402 section], even if the implementation doesn't implement all of ECMA-402." (Is it OK for 262 text to link to a 402 section?)
  • Limit IANA details in 262 (both in existing text and in this PR), and move those details into the new 402 section if appropriate.
  • I think HostTimeZoneIdentifier (or whatever we want to name it) can be 262 only. Not sure there's any benefit to overriding this in 402 unless I'm missing something.
  • Leave in 262 everything else in this PR that's not implementation-defined, like the Time Zone Identifier Record type, GetAvailableTimeZoneIdentifier, and the output shape of AvailableTimeZoneIdentifiers.
• Option 3 - Same as Option 2, except we'd also override AvailableTimeZoneIdentifiers in 402. The 262 version would be a UTC-only stub that would link to 402 for implementations that used non-UTC zones. The 402 version would match the PR. Both versions would have the same output shape.

My preference is (1) because I think it'd simplify things for implementers if all identifier-related text is in one document, instead of needing to flip back and forth to understand what they need to do. I'm sensitive to the tradeoff involved: it means parts of the 262 spec will require expertise that 262 editors probably won't have. That's risky, but so is splitting the text. Not sure there's a perfect solution here.

That said, I think (2) and (3) are also OK. Both would be better than the current state, so I'm happy to follow whatever y'all decide is best. I somewhat prefer (2) over (3) because if we need to split then it makes the most sense to me to have 262 deal with identifier algorithms while 402 deals with identifier data: how to build TZDB, which IDs are canonical, when to update TZDB, etc.

Happy to iterate with you if none of the options above look appealing.

[justingrant]

Hi @syg - Any thoughts on the three options I proposed above? Let me know if you'd like me to join the editor call if you want to talk it through in real time.

Ideally we could resolve this fairly soon, because we were hoping to be able to ask for Stage 2 for proposal-canonical-tz at the next TC39 meeting in 3 weeks and we'd like to rebase that proposal's normative text on top of whatever we decide here in this PR.

Also I just renamed HostTimeZoneIdentifier => SystemTimeZoneIdentifier and removed that AO from the host-defined section in the spec.

[syg]

@justingrant We would appreciate your dropping by the editor call to talk us through it. How about the next one on May 3rd at 2:30pm PT.

[justingrant]

How about the next one on May 3rd at 2:30pm PT.

Sounds great. I'll reach out in a DM to get an invite. Looking fwd to it.

[justingrant]

Whoo-hoo! Thanks editors and others for all your help getting this PR done!