add more polyfill options

[ljharb]

Currently, per mdn/content#31101 (comment), it seems that only core-js is currently listed as a polyfill implementation.

First, this didn't used to be the case - when it was a wiki, multiple options were often listed, so that suggests they were intentionally removed.

Second, it's wildly inappropriate for MDN to be "picking a winner". While removing all links to polyfills would address this, it wouldn't help users, and would make them more likely to copy/paste snippets instead of using actual production-quality polyfills.

I think a reasonable criteria, then, is that polyfills be well-maintained and be maximally spec-compliant (passing feasible test262 tests, for example). https://www.npmjs.com/org/es-shims meets this criteria along with core-js, and I think it's reasonable to include both where applicable.

I'd be happy to add the links, ofc, that's the easy part.

I don't agree with the slippery slope argument in the referenced PR, and if "having one option is better for users", then that is an argument to shut down Firefox entirely so that users have fewer browser options - but I suspect that Mozilla wouldn't want to argue that position (nor do I agree with it).

[hamishwillee]

The argument is not so much "having one option is better for users" as "having accurate, maintainable, and maintain information is better for users". MDN achieves that by limiting the number of options that we have to maintain, ideally and usually to a defacto standard option. We're not quite that restrictive usually, but we do require that things added to lists are well supported and have some kind of history that means we're not just being used as a means of self-promotion.
This is not a slippery slope theory - its the result of numerous cases where our lists of tools, websites, libraries, etc have gone out of date and we've had people adding their sites/tools as shameless self promotion.

Your links may well have been intentionally removed, either as part of the policy or because the associated API became stable.

In any case, I can't fairly comment on your library. My concern here would be that there might be X other people following in your footsteps with same argument as to why they should be "the one".

Let's see if there are some technical arguments for or against inclusion from @teoli2003 et al.

[ljharb]

While I'm sure that's theoretically possible, in practice, JS language polyfills have only 2-5 authors, which include myself and the core-js author. The list wouldn't likely get longer than 2 or 3 in almost any case, especially if the policy is to remove them once it's "stable".

(that said, i don't know what "stable" means; an API is usable in stage 3; being in stage 4 doesn't preclude changes to it; and the point at which polyfills are no longer necessary is when no user-supported browsers ship the API, which has no direct relationship with the standards process)

[hamishwillee]

Yes - I misused the term "stable". What I mean is "the point at which polyfills are no longer necessary". I don't know exactly how that point is defined, but I am certain there is a definition.

[teoli2003]

Hi all!

Context

Let me add some context to the current situation. Right after we migrated to GitHub at the beginning of 2020, we inherited the situation created by the Wiki era of MDN:

• Many code snippets on MDN were presented as polyfills and scattered in reference pages and guides. Their quality was usually very poor. Incomplete, sometimes plain wrong, they were often basic attempts to work around the missing features, not to emulate them as closely as possible. They were also unmaintained, sometimes used old JS and outdated patterns, or even worked in specific browsers!
• Next to these, there were links to external polyfills. Some were links to well-established sources, but many to blog posts or just GitHub gist… There was no guarantee of quality, most got added by their author and the wiki system didn't allow us to review them before the addtion.

We were (and still are) concerned by:

• Security. Polyfills are intended to be added to websites (either by including code or linking to an external file); they must not lead to security issues at the time of the recommendation or later.
• Maintainability. Like every piece of code, polyfills must be maintained; this wasn't the case for code included in our pages and for many linked polyfills.
• Exemplarity. We try to present modern JS. Often, polyfills use old patterns and syntax; this is normal as they work around the lack of new features. Including them in MDN was unfortunate as it added (and kept) old practices on pages.
• Simplification of code. We advocate for web developers to write for recent browsers; we don't see the need to teach them how to work around the lack of a feature supported by all modern browsers for years. Similarly to removing prefixes in CSS, we wanted to remove polyfills and shim for well-supported features.

These concerns are not all of the same importance; clearly, security concerns are the most important.

What we did

We took the following decisions:

• Not hosting polyfills on mdn/content. We don't have the bandwidth or the specialization to manage them.
• Where relevant, we will link to external polyfills and shims. Usually in the See also section.
• We avoid long lists of external tools/links; they are challenging to maintain. This is not specific to polyfills and shims and applies to all external links. Note: This doesn't mean that we want only one polyfill or shim, merely that we are cautious in adding them, discussing them carefully.

We cleaned MDN:

• We removed all polyfills and shims included on MDN as code snippets. (If you find more, open an issue; that's likely an oversight.)
• We included links to polyfills from a few well-known sources. The list is short and was not intended to be exhaustive.
• Without targetting exhaustivity, we removed a lot of mentions of polyfills and shims for features that are now well supported.

What we should do

I think we should do the following:

1. Set up a process to vet new polyfill sources. Without leading to bureaucracy, we should consider a list of criteria and, for example, validate them by vetting es-shim.
2. Document the process and rule for polyfills (this post is a good start).
3. Consider if we want to store polyfills in the YAML meta-documentation. (We froze the previous attempt to do this in feat(compat): list polyfills yari#6902). This would be a follow-up and shouldn't block the first two items.

We should decouple this discussion from the documentation and avoid blocking work like mdn/content#31101.

If the discussion moves forward before it, there is the opportunity to bring this to a broader group of maintainers at the next Mozilla Community Meeting (Jan 15th, 2024, I think)

Hope this helps.

[wbamberg]

It seems like there's agreement from everyone about roughly what we want but getting there is hard.

To make things a bit more concrete, perhaps we could have a new page "Polyfills" under https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures that includes:

1. MDN's general view of polyfills (basically, that they are useful but that we need to be careful making recommendations)
2. The criteria for including polyfill sources (as the minutes say, "Criteria could include conformance, web platform tests, sufficient adoption, which could be tough to quantify.")
3. The set of polyfills sources that are currently recommended for MDN
4. The process for proposing a new polyfill source for MDN

(Additionally we ought IMO to have a defined "Polyfill" section in the relevant pages, rather than just have them as "See also" links, to emphasise that they are a different sort of thing to "See also" links. But that's perhaps a separate thing.)

I'm not sure if the scope of this is just the JS docs. We do have polyfill links outside that area (e.g. https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API#see_also). But it's tempting to limit this conversation to JS, in the interests of getting something done.

As already noted, criteria are hard. I think one thing that worries maintainers is having a trickle of people trying to add links to their libraries, and having lawyery arguments about why they should be added, according to our criteria. Perhaps working backwards could help, in that we could ask, why should es-shims be added, and we can use that answer to shape criteria?

As for a process, it might make sense to make it a little more heavyweight than just "make a PR to the recommended polyfills list". But it could just be "start a discussion about adding a polyfill, and when there seems to be consensus, file a PR to update the recommended polyfills list, pointing at the discussion".

If this seems like a good approach, I'd be happy to draft a strawman PR for a "Polyfills" page that we could use to work out the details. Just to get things moving. (I'm also happy not to, if someone else wants to take this forward :).

[ljharb]

I can definitely help shape criteria. I think "adoption" as evidenced by npm download counts is a pretty solid item to include in the rubric, which core-js and es-shims both far exceed.

Spec-compliance is also necessary.

It'd also be useful to say that polyfill maintainers must be some kind of known quantity in the community - either via adoption of their package, or other means - which again core-js and es-shims would qualify for.

[Josh-Cena]

I agree: spec compliance and npm downloads are two of the biggest factors. I think we will be able to reject a lot of polyfills solely on the basis that they are not immune to overwritten globals. Author's credibility seems somewhat of a judgment call so I wouldn't write that formally.

[ljharb]

True, although for language polyfills at least, there’s really only 3-5 that have established themselves. We’re not talking about a lot of curation work.

[wbamberg]

True, although for language polyfills at least, there’s really only 3-5 that have established themselves. We’re not talking about a lot of curation work.

I'm happy for our "criteria" to be explicit (1) that it's a judgement call by the maintainers whether to include a source, not a measurement against precise criteria and (2) that the bar is high (much higher than is normal for an external link) and we don't expect to include more than a few sources.