Draft a page on polyfills #38326

wbamberg · 2025-02-25T18:40:31Z

...as promised in https://github.com/orgs/mdn/discussions/475#discussioncomment-11790206.

I haven't suggested we have a defined "Polyfills" section in reference pages (although I think we should). That seems like a thing we could deal with separately. I also talk a bit about Web/API, since we do link to polyfills there sometimes, too.

github-actions · 2025-02-25T18:41:57Z

Preview URLs

/en-US/docs/MDN/Writing_guidelines/Page_structures/Polyfills

External URLs (5)

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Polyfills
Title: Polyfills

https://github.com/es-shims (1 time) (Note! This may be a new URL 👀)
https://github.com/orgs/mdn/discussions (1 time) (Note! This may be a new URL 👀)
https://github.com/w3c/trusted-types?tab=readme-ov-file (1 time) (Note! This may be a new URL 👀)
https://github.com/zloirock/core-js/tree/master (1 time) (Note! This may be a new URL 👀)
https://www.npmjs.com/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-03-04 00:05:26)

Josh-Cena · 2025-02-25T18:44:01Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

+- Conformance to the specification for the feature for which they are providing an implementation.
+- Adoption by the web development community, as seen in metrics such as the number of [npm](https://www.npmjs.com/) downloads.
+
+Anyone can propose that MDN should recognize an additional source of polyfills by [filing an issue in the mdn/content repository](https://github.com/mdn/content/issues). However, the MDN maintainers expect the number of recognized polyfills linked from MDN to remain very small, to reduce the risk of recommending polyfills that cause problems for web developers.


I recommend sending issues in mdn/mdn, or mdn/mdn-community, since it rarely only concerns one or a few pages.

You mean, start a discussion in https://github.com/orgs/mdn/discussions? mdn-community doesn't seem to support issues. I would be happy to say that instead.

Oh yeah, a discussion in mdn-community or an issue in mdn/mdn is what I meant.

Josh-Cena · 2025-02-25T18:45:25Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

+
+### Integration of polyfills into pages
+
+When a page in the JavaScript reference documentation links to a polyfill, it adds the link in the "See also" section at the end of the page.


You can even copy the exact wording we use:

- [Polyfill for `featureName` in `project-name`](link)

And mention that they should be at the top of the list

Josh-Cena · 2025-02-25T18:45:59Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

+
+### Selected polyfills
+
+The [Web API reference documentation](/en-US/docs/Web/API) can link to polyfills that are maintained alongside the specification for the feature itself.


This seems a little vague. Maybe a few examples would help.

Hm, well for example the repo that hosts the trusted types specification includes a polyfill: https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill. Is it enough to add that as an example or do we need to come up with some general form of words for it? "maintained in the same repo as the spec" seems a bit restrictive?

Maybe "maintained by the spec champions"? "Officially endorsed"? I'm not sure how blessed that polyfill is; I just know that TC39 is very cautious not to endorse any polyfill, even one developed by the champions themselves. But in any case yes a link to that page is what I'm looking for at the minimum.

Maybe "maintained by the spec champions"? "Officially endorsed"?

But (if we're going to be picky) these also seem vague. Who are the spec champions, and do we know that they maintain it, or just that they trust the people who do. And what does official endorsement look like? I mean in the TT case, I'm pretty sure I want MDN to link to it, and I'm pretty sure I trust it, because it's in the same repo as the spec, and I would assume that the maintainers keep that repo under control. I suppose "maintained alongside" is supposed to be a version of "maintained in the same repo as", with a little extra wiggle room in case it ends up in a separate repo.

Each TC39 proposal has one or more champions. It is very rare for a champion to maintain a polyfill for that proposal, unless the champion happens to be me.

For web APIs, I'm not aware of the status, but I don't think there's that many web API polyfill authors out there.

Alright that sounds reasonable. Linking to that example would still help.

ljharb

This looks great to me, thanks!

Josh-Cena · 2025-02-25T19:17:18Z

There are some other policies I'd like to get clarification on, but I don't think we have agreement. For example, do polyfill links expire? Do we remove them after X years of baseline (my personal vote is that once we have a polyfill link it stays forever)? Is polyfill link inclusion by discretion of the writer, or are they part of the page template and omission is considered a bug? Are we required to have links for each and every API with available polyfills? And so on. Probably you intend for those to be clarified in follow-ups.

wbamberg · 2025-02-25T19:28:54Z

Probably you intend for those to be clarified in follow-ups.

🤣 probably yes. I don't have strong opinions on those issues personally. I suppose I think that "rules for rules sake" are not really worth it - for example, requiring that people include polyfills for APIs if they exist. For the Trusted Types API, for instance, I believe we want to talk about the polyfill, because we want general security guidance to talk about trusted types, and it doesn't yet have cross-browser support. Once TT has been shipping cross-browser for a few years, I'd be happy to take it out too. So it's really just a pragmatic thing.

We could just make this page about JS, where the story is more precise, but it seems more helpful to talk about Web APIs as well, even just in the sense of "describing our current slightly vague practice" rather than making up rules we must follow. And yes, we can always refine it later on.

Josh-Cena · 2025-02-25T19:38:45Z

I'm happy with this version.

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

hamishwillee · 2025-02-27T22:49:32Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

+```md
+- [Polyfill for `featureName` in `project-name`](link)
+```
+


When should it be removed? My understanding is that we remove the links when there is support in all browsers in the head revision. Needs to be confirmed.

See above ^ My personal vote is to keep them forever, since any responsible software needs to support browsers that are at least a few years old.

I have no firm opinion. If ^^^ is agreed, then it is worth spelling out the policy though.

As #38326 (comment) says, I'd prefer to defer these conversations. This PR is just to move things along a bit, so we can even have a documented polyfill policy, and allow other polyfills than core-js. That alone has taken several years to get done!

hamishwillee · 2025-02-27T22:50:59Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

+Sources are selected by the MDN maintainers based on the following criteria:
+
+- Conformance to the specification for the feature for which they are providing an implementation.
+- Adoption by the web development community, as seen in metrics such as the number of [npm](https://www.npmjs.com/) downloads.
+
+Anyone can propose that MDN should recognize an additional source of polyfills by [starting a discussion in the MDN discussion forum](https://github.com/orgs/mdn/discussions). However, the MDN maintainers expect the number of recognized polyfills linked from MDN to remain very small, to reduce the risk of recommending polyfills that cause problems for web developers.


I would give this its own heading. Depending on how the discussion falls out in https://github.com/mdn/content/pull/38326/files#r1970347778 I would move the whole heading up a level, shared by both web APIs and JavaScript.

I split the policy at this level because I think currently our JS policy is much more advanced than our Web/API policy. In fact you can't really call our usage in Web/API a policy at all, I just tried to document our practice as I see it. I don't know if we want to allow "non-spec WG" polyfills for Web/API at all, we haven't even had that conversation, And, again, the idea of this PR is to unblock the situation wrt JavaScript polyfills.

I will add the extra heading though 👍

…ndex.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee · 2025-02-27T23:13:43Z

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

@@ -5,7 +5,7 @@ page-type: mdn-writing-guide
 sidebar: mdnsidebar
 ---

-This page outlines MDN's policy for including polyfills in two areas of the reference documentation: the [JavaScript documentation](/en-US/docs/Web/JavaScript), and the [documentation of Web APIs](/en-US/docs/Web/API).
+This page outlines MDN's policy for including polyfills in the reference documentation for [JavaScript](/en-US/docs/Web/JavaScript), and [Web APIs](/en-US/docs/Web/API).


I think I left a comma in there that I shouldn't have.

…ndex.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* origin/polyfills: Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

hamishwillee

LGTM given the constraints. Approved but not merged so you can decide if you've had enough feedback.

wbamberg · 2025-03-04T01:08:03Z

Thanks for the review Hamish. This has had enough review and previous discussion that I'm happy to merge :).

ljharb · 2025-03-04T01:15:55Z

Awesome! Does that now mean I can prepare a PR to add all the es-shims polyfills?

Josh-Cena · 2025-03-04T01:53:16Z

Yes, please do so :P Wherever we have core-js an equivalent es-shims link should be added too.

* Add a page on polyfills * ... * Review * Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Review feedback --------- Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

wbamberg added 2 commits February 25, 2025 10:35

Add a page on polyfills

883d90b

...

c084dd0

wbamberg requested a review from a team as a code owner February 25, 2025 18:40

wbamberg requested review from hamishwillee and removed request for a team February 25, 2025 18:40

github-actions bot added Content:Meta Content in the meta docs size/s [PR only] 6-50 LoC changed labels Feb 25, 2025

Josh-Cena reviewed Feb 25, 2025

View reviewed changes

ljharb reviewed Feb 25, 2025

View reviewed changes

Review

19b9822

github-actions bot added size/m [PR only] 51-500 LoC changed and removed size/s [PR only] 6-50 LoC changed labels Feb 25, 2025

hamishwillee reviewed Feb 27, 2025

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 27, 2025

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md Show resolved Hide resolved

hamishwillee reviewed Feb 27, 2025

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 27, 2025

View reviewed changes

Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/i…

6c95ed4

…ndex.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee reviewed Feb 27, 2025

View reviewed changes

wbamberg and others added 3 commits March 3, 2025 15:45

Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/i…

066ebcb

…ndex.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Review feedback

60c1dbc

Merge remote-tracking branch 'origin/polyfills' into polyfills

dea3c68

* origin/polyfills: Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md

wbamberg requested a review from hamishwillee March 4, 2025 00:04

hamishwillee approved these changes Mar 4, 2025

View reviewed changes

wbamberg merged commit 15be229 into mdn:main Mar 4, 2025
8 checks passed

ljharb mentioned this pull request Mar 5, 2025

add es-shims polyfills #38460

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Draft a page on polyfills #38326

Draft a page on polyfills #38326

wbamberg commented Feb 25, 2025 •

edited

Loading

github-actions bot commented Feb 25, 2025 •

edited

Loading

Josh-Cena Feb 25, 2025

wbamberg Feb 25, 2025

Josh-Cena Feb 25, 2025

Josh-Cena Feb 25, 2025

Josh-Cena Feb 25, 2025

wbamberg Feb 25, 2025

Josh-Cena Feb 25, 2025

wbamberg Feb 25, 2025

ljharb Feb 25, 2025 •

edited

Loading

Josh-Cena Feb 25, 2025

ljharb left a comment

Josh-Cena commented Feb 25, 2025

wbamberg commented Feb 25, 2025

Josh-Cena commented Feb 25, 2025

hamishwillee Feb 27, 2025

Josh-Cena Feb 27, 2025

hamishwillee Feb 27, 2025

wbamberg Mar 3, 2025

hamishwillee Feb 27, 2025 •

edited

Loading

wbamberg Mar 3, 2025

wbamberg Mar 4, 2025

hamishwillee Feb 27, 2025

hamishwillee left a comment •

edited

Loading

wbamberg commented Mar 4, 2025

ljharb commented Mar 4, 2025

Josh-Cena commented Mar 4, 2025


		### Integration of polyfills into pages

		When a page in the JavaScript reference documentation links to a polyfill, it adds the link in the "See also" section at the end of the page.


		### Selected polyfills

		The [Web API reference documentation](/en-US/docs/Web/API) can link to polyfills that are maintained alongside the specification for the feature itself.

Draft a page on polyfills #38326

Draft a page on polyfills #38326

Conversation

wbamberg commented Feb 25, 2025 • edited Loading

github-actions bot commented Feb 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ljharb Feb 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ljharb left a comment

Choose a reason for hiding this comment

Josh-Cena commented Feb 25, 2025

wbamberg commented Feb 25, 2025

Josh-Cena commented Feb 25, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee Feb 27, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee left a comment • edited Loading

Choose a reason for hiding this comment

wbamberg commented Mar 4, 2025

ljharb commented Mar 4, 2025

Josh-Cena commented Mar 4, 2025

wbamberg commented Feb 25, 2025 •

edited

Loading

github-actions bot commented Feb 25, 2025 •

edited

Loading

ljharb Feb 25, 2025 •

edited

Loading

hamishwillee Feb 27, 2025 •

edited

Loading

hamishwillee left a comment •

edited

Loading