-
Notifications
You must be signed in to change notification settings - Fork 104
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API surface and scope guidelines #442
Comments
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:
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.
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. |
@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. |
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" ( 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. |
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? |
Proposal:
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? |
|
Preface proposal for the outline of the approach:
|
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 |
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. |
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
andPluralRules
). 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:
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.
The text was updated successfully, but these errors were encountered: