MDN-RFC-001: MDN wiki pages shouldn't be a distributor of polyfills

MDN
#1

Hi all!

I like how Rust or DevTools are discussing major changes through RFC threads. So, here I go:

MDN-RFC-001: MDN wiki pages shouldn’t be a distributor of polyfills

For those not knowing what I’m talking about, here’s what polyfills are (see Polyfills and the evolution of the Web and the MDN glossary):

Polyfills are a valuable part of Web architecture, because they promote the adoption of new features during the implementation process. However, polyfills can also create problems for standardization efforts and therefore for the future of the Web.

MDN authors and distributes polyfills as part of many reference pages. Examples

Problems

  • The UX is terrible: The polyfills are distributed in the wiki 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.
  • We can’t maintain them: 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. (shudder)
  • We do not conform to the advice for polyfill distributors from the W3CTag:
    1. We don’t check if we host bad polyfills that are hurting the web. They’re in the wiki and editable at any time.
    2. We do track spec changes more or less, but we are unable to update the polyfills accordingly.
    3. We’re not a CDN for polyfills, we don’t bundle them (someone apparently started doing that for us), nor can we guarantee any integrity, or checksums, caching, or anything the like.

Proposed changes

  • We should remove polyfill code blocks from the wiki pages.
  • They need to live in a repository where we can guarantee that we’re conforming to the W3CTag polyfill distribution guidelines (see above).
  • We still want to offer polyfills to our readers but we should link to a trusted polyfill source rather than providing our own untrusted ones inline.
  • We should investigate if it’s worth creating our own repository (mdn/polyfills) for which we’ll create a community that cares about polyfills, or if we start partnering and linking to existing communities and services like https://polyfill.io or others.

–Florian

6 Likes
#2

I agree to this and would add the following points:

  • I used to tag some pages with polyfills on the French JavaScript sections: https://developer.mozilla.org/fr/docs/tag/Polyfill (careful though, that’s most probably a very small subset)
  • I know some colleagues/people using them already so I’d +1 an MDN repo if it has proper due maintenance. Is it worth the effort? I can’t say. I believe that having at least a link (from the See Also section would be better)
  • I noticed polyfills on the JavaScript section are more frequently edited than the rest of the content if the page has a polyfill. This stresses the point “we can’t verify the safety of changes”. Edits also revolves around efficiency vs. readability (no “edit war” though :slight_smile: )
1 Like
#3

+1.

I think there’s a critical difference between embedded code that’s intended to be read and digested in order to illustrate something, and embedded code that’s intended to be copy/pasted into a program to do some magic. I’m very uncomfortable with any place in the Wiki where we embed big slabs of code for the latter purpose, and polyfills clearly fall into that category. As do things like
this and this.

But there are 2 questions in here which we could separate:

  1. should we maintain polyfills in the Wiki?
  2. should we maintain polyfills at all?

Your second “problem”, “We can’t maintain them” is actually an argument about (2) not about (1).

I think the answer to (1) is a definite “no”. As for (2), I’m not sure, but the polyfill service you linked to seems well-established, quite comprehensive and documented, so I think I’d vote “no” on (2) as well.

3 Likes
#4

I’m on the side of not maintaining polyfills on MDN.
I think polyfill-io is making an amazing job at maintaining the polyfills.
https://github.com/Financial-Times/polyfill-service/tree/master/polyfills
They have an incentive to do so that MDN doesn’t have which is that they host cdn.polyfill.io (now used in so many places on the web), so their polyfills had better being well-maintained. Most of the code is MIT-licenced too.

  • We should remove polyfill code blocks from the wiki pages.

+1

  • They need to live in a repository where we can guarantee that we’re conforming to the W3CTag polyfill distribution guidelines (see above).

+1

  • We still want to offer polyfills to our readers but we should link to a trusted polyfill source rather than providing our own untrusted ones inline.

Polyfill-io is the perfect candidate in my opinion

  • We should investigate if it’s worth creating our own repository (mdn/polyfills) for which we’ll create a community that cares about polyfills, (…)

I’m not sure there is value here. If there was not enough energy to maintain in the wiki, there is no good reason there will be more energy to contribute to a repository.

  • (…) or if we start partnering and linking to existing communities and services like https://polyfill.io or others.

Yes, linking can happen without partenering.

One thing that Mozilla could bring (beyond code and docs) is forking polyfill-io and making sure it’s easy to host for people who would like to be independent of the cdn.polyfill.io domain name. Maybe host your own CDN-backed version so it’s easy for people to switch if one goes down.

Another thing Mozilla can do is contribute to polyfill-io whenever something got implemented in Firefox

3 Likes
#5

+1 to linking to polyfill.io where appropriate. Should info on polyfills also be included in the compat tables?

1 Like
#6

I think using polyfill.io is the right call; if not for them, I’d have favored creating our own. I’m glad we don’t have to. I do think we should engage with them and keep an eye on things to be sure they stay relevant and current instead of someday down the road falling into disrepair, but that is hopefully a limited possibility.

I also do feel we should consider directly engaging with them in terms of collaboration or cooperation. It seems likely to be a relationship worth fostering.

Sheppy

Eric Shepherd
Senior Technical Writer

MDN Web Docs: https://developer.mozilla.org/

Blog: http://www.bitstampede.com/

Twitter: http://twitter.com/sheppy

#7

Creator of polyfill.io here, though much of the work is now done by Jake Champion now that I’ve left the Financial Times (which sponsors much of the development work). I think this is a really terrific suggestion. I’ve been trying for a long time to encourage wider community collaboration on the polyfill.io sources, especially because the core team can’t know the best way to simulate every feature. We have and do put a lot of thought into delivery and distribution, dependencies, encapsulation, and optimising browser targeting, and it would be awesome if more of the developers who are closer to real world use cases and implementations could contribute more of the polyfills themselves.

3 Likes
#8

I think there is one more facet to this worth considering: these inline polyfills give a rough idea about how some of these polyfills are/can be implemented which can be a really useful insight to the person reading about a new feature (to learn about how it relates to existing technology and features). I do agree this wasn’t the primary reaction to most people, as most people copy-paste code when they see code (and I’m not jus bashing all those other people, I’m guilty of copy-pasting MDN polyfills myself, it was convenient), so if there was a way to keep this added perk of implementation insight but link to a trusted source, that would be great. I can imagine linking to polyfill.io, and where it makes sense, describing working principle of the functionality the polyfill provides to keep this bit of insight more-or-less intact (maybe even add a link to the polyfill source, too).

3 Likes
#9

I love this point. Polyfills can be educational because of the very nature of what they do. Sometimes referring to them from articles when discussing interesting tricks or techniques might be useful.

#10

I am really enjoying this discussion. I agree that we should find a good way to deal with polyfills on MDN - whether it is a simple matter of removing them and pointing elsewhere, or whether we can do something cleverer with a service like polyfill.io (hi Andrew!). I will add an item to our roadmap for Q2, to write a plan on how to deal with this, and then put the plan into action.

Ideally I’d like one of our writers to take the lead on this, and we should get some help from the lovely web community.

#11

I agree with Florian’s suggestions, and I’ll keep some time open in Q2 to help Chris.

#12

IMHO, the best thing todo would be to add the contents of the source from polyfill.io@github inside the wikipages using the live-examples feature or the like…

This way:

  • MDN does not need to keep track of the actual polyfill-code
  • yet at same time provide the insight for the developers interested that read the article about the feature
  • Provide info for interested collaborators to improve the polyfill(s), by a direct link to the maintainers sources.
  • which is again IMHO the added value of MDN.
#13

I’m intrigued by the idea of embedding polyfills from other sources for the convenience of readers.

There are questions, though.

  • Are polyfills important enough to enough people to make this worthwhile?

  • Is the cost in terms of page load time and size worth the benefit?

  • What implementation difficulties are there? Certainly there’s cross-site loading that needs to be dealt with, at least, so probably some security stuff to deal with.

  • Is the cost in terms of implementation time and effort worth the benefit?

I’ll add that even assuming we do it, it would be worth considering having them behind a widget you have to click to expand or open the polyfill view, to reduce clutter.

With all that written down, I strongly suspect that just linking to the polyfill is the best way to go. But we should design a standard appearance and design for it (and hopefully a macro to aid in easily creating polyfill reference – or embedding – boxes).

Sheppy

#14

It looks like the last update to this discussion was over two years ago. Any updates since then?

I discovered this conversation after trying to add a polyfill to the Array.prototype.includes() reference and seeing a note and link here.

I’d love to contribute to this in any way possible if you decide to move forward. I’ve been maintain my own collection here for a while.

#15

I’m picking this back up again…

I have seen a few polyfill sections floating about, but agree with the points made about linking rather than including.

My question is should there be a dedicated polyfill link (if so how) or should it be added to ‘See also’ at the bottom of the page?

#16

I think a “See also” link is fine.

#17

Thanks @chrisdavidmills