OWD project: Fix how MDN distributes Polyfills

[Elchi3]

This project proposes that we work on fixing how MDN distributes Polyfills.

Originally proposed in the MDN discourse https://discourse.mozilla.org/t/mdn-rfc-001-mdn-wiki-pages-shouldnt-be-a-distributor-of-polyfills/24500 but never rolled out, because the MDN wiki didn't really allow to make mass changes. This is now much more approachable with MDN in git.

Problem statement

MDN reference pages often contain large code blocks of Polyfills. This is bad for a few reasons.

• The UX is terrible: The polyfills are distributed in the reference page inside the usual <pre> code blocks which are normally used for static code examples and create a giant blocks of code you normally don’t want to read, but need to copy & paste into your project in order to make use of the polyfill.
• Maintenance is an impossible task: The MDN staff contributors and the core community lacks knowledge and time for of looking after changes to polyfills. Code of polyfills can be really complicated as it implements functions and algorithms described in e.g. the ECMAScript specification or needs to handle weird edge cases. The code aims to be correct and fast, which can be tricky, too. There are bugs filed against MDN polyfills; they remain unresolved.
• Translations outdate, too. I haven’t even looked at how bad polyfills are on outdated wiki translations.
• We do not conform to the advice for polyfill distributors from the W3CTag:
  • We don’t check if we host bad polyfills that are hurting the web. They were in the wiki and editable at any time.
  • We do track spec changes more or less, but we are unable to update the polyfills accordingly.
  • We’re not a CDN for polyfills, we don’t bundle them (someone apparently started doing that for MDN), nor can we guarantee any integrity, or checksums, caching, or anything the like.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Medium. Need to identify how many pages involved but it is not all reference pages.
Dependencies	Need to agree on trusted Polyfill sources
Community enablement	Yes. This task is quite self-contained and contributions to update as many pages as possible are welcome
Momentum	N/A
Enabling learners	Not really. Sometimes remove large distracting code blocks from reference pages
Enabling professionals	Probably. You want to trust MDN about its Polyfill recommendation
Underrepresented topics / ethical web	N/A
Operational necessities	N/A
Addressing needs of the Web industry	Might help address compat pain point as Polyfills are part of the story there.

Proposed solutions

• We should remove polyfill code blocks from the MDN pages.
• We still want to offer polyfills to MDN readers but we should link to a trusted polyfill source rather than providing untrusted ones inline on the pages.

Task list

• Confirm Polyfill removal and linking to trusted sources is the way forward.
• Figure out trusted sources for Polyfills
• Replace inline Polyfill code with links to trusted Polyfill sources

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].

[dontcallmedom]

Thinking aloud, would it make sense to have a curated list of polyfills be part of BCD? It's the sort of data the feels related in terms of helping developers figure out if and how they can use a feature, and the BCD repo could host a curation process based on some of the criteria, documenting some the pitfalls?

[Ryuno-Ki]

Personally, I head over to https://polyfill.io/v3/ by @Financial-Times if I need a polyfill for something. Modernizr could be considered another trusted source.

Is this issue also about Ponyfills? https://github.com/sindresorhus/ponyfill#how-are-ponyfills-better-than-polyfills
Or Prollyfills? https://kikobeats.com/polyfill-ponyfill-and-prollyfill/

[Elchi3]

I think having Polyfills with the "Browser compatibility" section (i.e. the compat table) makes sense. That's probably where readers usually care and look for solutions. Having BCD curate Polyfills is also a good idea since the BCD community knows a lot about compat already.

Another project to talk to is https://github.com/zloirock/core-js. It also offers a lot of polyfills and is widely used.

I think there is consensus we don't want Polyfill code to be shown on MDN docs (or even be hosted inline) anymore because it adds no value.

We should think about what we want instead:

• Just a simple link to (a) polyfill source(s)?
• A link plus some handy instructions on how to install it? (a la npm install etc)
• Some really fancy button that can be pressed and then updates the compat table to takes into account how the Polyfill offers broader support?
• ... other ideas?

[hamishwillee]

My two bits:

1. I lean towards a simple link as opposed to installation instructions. The more you write, the more you have to maintain - and that is hard for off-site resources
2. If in BCD, why not just specify this as a normal subfeature, indicating the browser versions it is known to work in?
3. My reservation about including it in BCD is bandwidth; that team feels pretty stretched.
4. Yes, I am in favour of removal of the polyfills from source and linking to best alternatives we can find.

[teoli2003]

Yes, I also think we shouldn't host them, only link (directly or via structured data in front-runner, in mdn/browser-compat-data, elsewhere).

We discussed this project yesterday.

To move it forward, we need a few decisions.

I opened: mdn/content#7841 to decide for what features do we want to have polyfills. This decision will already help us to clean what we have (and then to make a useful inventory of the situation)

[Elchi3]

A recent discussion on this topic happened here: https://github.com/orgs/mdn/discussions/140

The outcome is to create a yaml front-matter key on MDN pages called polyfill that is a link (or an array of links) to polyfills, hosted externally. This key will be used to render a link to the polyfill below the compat table.

A draft implementation is at mdn/yari#6902

[hamishwillee]

FYI this came up in OWD SC meeting today. @estelle Wanted to know if

• core.js was a trusted polyfill source, and if not what sources are trusted
• What the policy is for removal/adding

The broad feeling was that core.js was a kind of defacto standard. Also that polyfills are good when you only have one browser implementation, but not when there is broad implementation because people shouldn't be loading these unless they are needed. Policy might be something like "remove when in all current browsers"

[estelle]

What is the status of this?

[teoli2003]

This is on hold.

[zloirock]

Policy might be something like "remove when in all current browsers"

core-js will be moved to a similar policy by itself from the next major version -) However, polyfills are also bug fixes, and most bugs are not documented in MDN. Many such bug fixes are required even if everything in MDN compat data is green.

[Elchi3]

I'm closing this as not planned for the moment. We've tried multiple times to get something implemented. We're happy to help with this in case anyone wants our thoughts and feedback on this project idea but I don't see us picking up mdn/yari#6902 or related discussions in the near future.