API surface and scope guidelines

[zbraniecki]

This issue is in a slight relation to the conversation in #435.

I'd like to try to develop an explicit consensus on the scope of ECMA402 target API surface.

Given enough time, and using ad extremum reasoning, all possible feature will be requested. Not just 100% of the ICU API surface, but likely more.

How we want as a group to react to that?

Over the last couple years, I definitely saw more cases of arguments along the lines of "ICU already has it, so let's add it" or "CLDR gives it to us, so why not".

Are we ok slowly extending the ECMA402 API surface until it covers 100% of ICU and CLDR?

Is there a line we don't want to cross? Is there a clear difference in target API surface compared to ICU/CLDR that comes from the nature of the Web, JS environment and so on?
For example, we could argue that since JS standard is forver, we want to keep the API surface significantly smaller than what a library that can deprecate APIs can do.
JS environment is commonly used in privacy-unfriendly situations (Web), so each API can and will be a target of malicious attempt against the user. Some user interactions can be facilitated via DOM/HTML alleviating the risks (datetime pickers, calendar pickers, range pickers and other UI widgets that require rich interactions). Does it impact our decisions or do we prefer to ensure client-side pickers for all UXes are fully possible via ECMA402 APIs?
Or we could claim that since JavaScript is higher level, certain low-level abstractions are unnecessary.
Or we can make an argument that we intend to keep ECMA402 a significantly simplified compared to ICU due to our target userbase having less expertise than typical ICU users (hence, options bag over skeletons, and reluctance to work with datetime patterns).
We could also argue that the difference is in that we want to minimize the payload to enable implementers in highly constrained environments.
Or we could state that we want to continue ensuring that the specification is not ICU/CLDR bound and thus "ICU has it" is not a good argument at all.

Each one of those, and likely more, of the arguments can be challenged and a counter argument can be made.

When I started contributing to ECMA402, with Caridy and Eric at the helm, I felt this topic was fairly well understood, because we were a very tiny group working for years to add a single function and a single new class (getCanonicalLocales and PluralRules). It was my understanding that we want to expose 5-10 most common Intl APIs and stop there, leaving as much as possible to user libraries.

I think with the success of ECMA402 comes a shift of perspective, and with the drastic reduction of diversity in implementations comes a simplification of the road from a request filled to Stage 4.

This is, in my opinion, a good thing (the success of ECMA402, not the reduction in diversity), but a potentially negative consequence is that it makes it easy to continue on a ICU-compliance treadmill until something makes us stop and revisit.

In the world in which everything we standardize stays as part of the JS platform forever, I'd love us to make an attempt to anticipate that "something" and try to avoid having to learn about it the painful way a flock of WebAPIs went when a high number of peripheral APIs have been proposed (WebBattery, WebBluetooth, WebGPS, WebSensors etc.) and many had to be later painfully backtracked.

I think we are reaching the original goal of the ECMA402 as of the time when I joined - we have DateTime, Number, PluralRules, RelativeTimeFormat, Locale, ListFormat, DisplayNames, Segmenter, unit formatting (within NumberFormat rev. 2) and MessageFormat in the works.

I believe there's an argument to be made that the scope is sufficient for a JS stdcore library and we can switch gears to polish the APIs we have and cool down on extending the surface.
The argument can also be made that there's no reason to stop. We have the momentum, best practices and good velocity and we can keep pumping out new APIs for an increased number of use cases.

I believe the latter is particularly natural reaction, since once developers start using ECMA402 APIs, they'll always find "just one more thing they need" and it's reasonable for them to request an extension of ECMA402, rather than pull a library just for a single feature.

In the light of that, I'd like to start a conversation about:

• the revision of the intended surface of ECMA402
• how is it different from "everything"
• how does the the JS environment affect what we want in
• what we don't want to add
• how do we want to evaluate requests for in/out of scope

I hope such guidelines, while likely hard to design, will pay off over the next 2-5 years as the current ECMA402 APIs get more usage and we receive an increased number of requests for many APIs useful to a smaller groups of users.

[sffc]

I discussed my perspective on this subject in tc39/proposal-intl-numberformat-v3#5. I think new features should at a minimum cover these three things:

1. The feature must have multiple stakeholders. This is used as a mechanism to ensure that the feature has broad appeal and use cases.
2. The feature must have robust prior art, e.g., in CLDR, ICU, or Unicode. Our job is to bring features that i18n experts have already solved to JavaScript developers, not to invent new solutions to those problems.
3. The feature must be difficult to implement in user land (such as a locale data dependency). Features in Intl must bring something to the table that a third-party library wouldn't be able to do with the same level of efficiency and performance.

Over the last couple years, I definitely saw more cases of arguments along the lines of "ICU already has it, so let's add it" or "CLDR gives it to us, so why not".

Those are both very bad reasons for proposals in my opinion. I would not support proposals whose only reason for existing is because it happens to be in ICU.

The one nuance to this is that if we are already working on a proposal, e.g. Intl.Segmenter, where the primary use case is word breaks, but CLDR/ICU lets us also support sentence breaks, then maybe we can throw that in since it's easy, as long as it isn't otherwise harmful to the ecosystem (as was the case with line breaks). However, I wouldn't support a standalone proposal for adding sentence breaks, unless that feature request stood on its own merits.

I think we are reaching the original goal of the ECMA402 as of the time when I joined - we have DateTime, Number, PluralRules, RelativeTimeFormat, Locale, ListFormat, DisplayNames, Segmenter, unit formatting (within NumberFormat rev. 2) and MessageFormat in the works.
I believe there's an argument to be made that the scope is sufficient for a JS stdcore library and we can switch gears to polish the APIs we have and cool down on extending the surface.

Although I don't want to entirely rule out the possibility of expanding scope if the committee thinks it is prudent, I agree with this sentiment. Once MessageFormat and User Preferences are finished, which may take the rest of 2020 and much of 2021, I see most of the work going forward as incremental improvements to the existing APIs. Intl.NumberFormat V3 is a good example of that: I scrubbed all the existing NumberFormat feature requests, identified the ones with strong merits, and put them together into a proposal. Once this proposal is merged, I would consider Intl.NumberFormat more-or-less complete.

[sffc]

@mathiasbynens Would you be able to shed some light on how other standards bodies filter feature requests to determine which ones are most important to adopt? The issue is that we have a large inflow of feature requests in ECMA-402, and we are looking for prior art on guidelines to determine which feature requests are most worthwhile adding to the spec.

[mathiasbynens]

The key thing to look for in new proposals is the motivation. What is the problem this proposal is trying to solve? What is the real-world use case of it?

To take an existing feature as an example, "I want to make it possible to easily reverse an array" (Array.prototype.reverse) is not a good motivation. Instead, answer the questions: why do people want to reverse arrays? What concrete use cases does it solve?

Standards bodies are always trying to weigh the costs vs. the benefits of adding new features. Without a solid motivation, the proposal doesn't pay for itself.

Sometimes it's possible to quantify this, e.g. if there's already a userland library that solves just this one specific problem, and it gets millions of npm downloads per week, that might be a good indicator of developer interest. But sometimes that data isn't there, and then it goes back to having a strong motivation.

[sffc]

Thanks! Are you aware of a standard set of criteria to put proposal motivation up against? Like, if one stakeholder believes that a proposal is motivated, but other stakeholders are unconvinced, how do you break the deadlock?

What often happens in TC39 is that delegates say things like, "I'm not convinced that this proposal is warranted, but it seems harmless, so I'm not going to block advancement." Can we turn qualitative opinions about the merits of a proposal into a quantitative set of benchmarks?

[zbraniecki]

Proposal:

• Can the feature be easily handled in the userland - high data overhead, or complex logic that is easy to done wrong
• Is the future high-profile - lots of websites need it, or very high profile web apps (Calendar, Travel Booking, etc.) need it, and data/logic is hard to do in userland
• Is the feature critical for web to be multilingual - some features that we don't see a lot of use of, we may decide are crticial for the web to have in order to be multilingual

In all cases, if the request passes the checks, we still should aim to design the smallest possible surface, with smallest data payload for the most generic use, and leave outliers to userland.

How does it sound?

[longlho]

• Can the feature be easily handled in the userland: This would be false to most i18n features bc CLDR are both heavy and not exposed in any browser.
• Is the feature high-profile: Should we figure out some sort of KPIs for this?
• Is the feature critical for web to be multilingual: I think this needs to be teased out a bit since critical is pretty vague.

[zbraniecki]

Preface proposal for the outline of the approach:

ECMA-402 standard should be as small generic as possible to supply sufficient internationalization capabilities for JavaScript to lower the barrier to turn JavaScript application for global audience.

Since web standards have no good deprecation way, each API should be very well designed as there is no "v2" opportunity, API surface should be kept as small as possible and because ECMA-402 is meant to be implemented in many resource constrained environments, the payload required to support ECMA-402 should be kept as small as possible as well.

The balance the ECMA-402 is trying to strike is the never-ending stream of additions vs. the need to remain small, lean and stable for very long (10+ years) timeframe of maintenance.

At the moment, ECMA-402 WG believes that all major Internationalization APIs necessary for its scope are already standardized or in advances stages, and the focus is on improving the existing specification quality and minor API tweaks.
Adding a new functionality, especially one that requires new data will require strong justification.

For those reasons, ECMA-402 will remain very conservative in extension of the API surface and a proposal must pass a list of checks to be considered necessary for ECMA-402 scope.

[zbraniecki]

I agree with Shane that extensive prior art is a good checklist point - we're not "designing" intl APIs, we "expose" a subset of very mature, well battle tested APIs.

Also: I would like to express the difference between a proposal that increases user control, vs proposals that add new data and features. For example eraDisplay proposal allows users to control the display better, with very small change to algo. RelativeTimeFormat is a huge new API that adds data and significantly increases the surface. I'd like to see this difference expressed in the checklist.

[sffc]

2020-11-05 meeting minutes: https://github.com/tc39/ecma402/blob/master/meetings/notes-2020-11-05.md#api-surface-and-scope-guidelines-442

Action item is on me to open a PR. This should be included with general contribution steps in CONTRIBUTING.md.