Polyfill.io

Common contribution scenarios

A few scenarios come up time and again on our issue tracker. If you want to contribute, and one of the scenarios below describes what you want to change, follow the steps to achieve a painless and rapidly merged pull request!

A particular polyfill is being served to the wrong browsers / not enough browsers

Commonly, people want to take a polyfill we already have and get us to serve it to a browser that we currently don't target with that polyfill. Often this is because it's a less common browser and we just haven't tested the polyfill in that browser, so adding the extra browser as a target does make sense.

  1. Update the relevant polyfill's config.json file (here's an example) to add, remove or change the value of the browser version constraint
  2. Check that your change is in line with the documentation on writing configuration JSON
  3. Open a pull request with the following information
  4. Check reliable sources of browser support information, e.g. MDN, caniuse and Kangax. Tell us what these sources say about the browser/polyfill combo that you want to add or remove, and link to the relevant pages from your PR.
  5. Explain how you have tested support (or lack of) in the browser concerned. Ideally, include a screenshot of the relevant browser running our test suite for that feature.
  6. State your agreement to our contribution terms.

The service is incorrectly identifying a browser

Although there are only five significant rendering engines (blink, presto, trident, gecko and webkit), there are lots of distinct browsers and user agents. We don't currently support anywhere near all of them, but are happy to add support on demand.

  1. Find out the User-Agent header value sent by the browser
  2. Load https://cdn.polyfill.io/v2/polyfill.js?ua={UAHEADER} and take note of the detected, normalised browser name (e.g. 'chrome/40') that is displayed in the comment at the top of the output
  3. Work out which of our existing families the browser matches, e.g. Firefox for iOS is most usefully seen as an alias of Safari for iOS.
  4. Make the apppropriate change:
    • If the browser is misrecognised as another browser that we support (e.g. niche Acme browser is recognised as 'chrome' but it's actually gecko based), the family is right but the version number is wrong, or it's coming up as 'unknown', this is probably a problem with the node useragent module. Check our UA.js module to ensure we don't have any crazy aliasing rules that are misbehaving, then raise your issue in the ua-parser/uap-core repo, not here (here's an example of a really good PR).
    • If the family is an unsupported browser but a supported one would suffice and the version is correct, make the niche browser an alias for the supported one in the UA.js module.
    • If the family is an unsupported browser and we have no existing supported family that would be comparable, consider creating a new supported family, which will require updates to UA.js, all relevant polyfill config.json files, and the documentation in /docs. This adds a significant maintenance burden, and we will strongly prefer to make an imperfect alias rather than create a new supported family.
  5. Open a PR with the following info: the raw UA string and as many variations as you've found, the normalised UA name that we currently produce for that raw UA, and a description of your rationale for the change you've made.
  6. State your agreement to our contribution terms.

You want to add support for a feature not currently in the service

You want to add a new polyfill? That's brilliant. Here's how you do that:

  1. Search for existing polyfills online - has someone already created one that you can use?
  2. Make sure that the polyfill correctly implements the aspects of the spec that it seeks to emulate
  3. If you want to use a third party polyfill available on npm:
    1. Write a well defined config.json, following the guidelines for configuring polyfills, and including an install section refering to the source module and path.
    2. Add the npm module to our package.json file and regenerate the shrinkwrap.
  4. If you want to write an original polyfill:
    1. Follow our guidelines for the best practice architecture of original polyfills
    2. Save your polyfill code in a file called polyfill.js in a new subdirectory of the /polyfills directory, named for the JavaScript global that accesses the feature (or if the feature has no JavaScript API, use a descriptive name prefixed with a tilde, e.g. ~html5-elements)
    3. Add a well defined config.json, following the guidelines for configuring polyfills.
    4. Write a reasonably comprehensive set of tests in a tests.js file, and check that they pass in all the browsers you have targeted.
  5. Add a feature detect in a detect.js file if it's possible to detect the feature via a JavaScript expression.
  6. Run grunt ci to check that library still passes our continuous integration tests. For help connecting to a Sauce Labs account, see running tests on Sauce Labs.
  7. Open a pull request, including links to evidence of browser support from reliable sources, ie MDN, caniuse and/or Kangax, and a screenshot of the test results in a targeted browser.
  8. State your agreement to our contribution terms.

A polyfill needs to be updated from a third party source

We have an out of date version of a 3rd party polyfill in our repo, and you want to update it to the latest version.

  1. Bump the version of the package inside package.json and re-run npm shrinkwrap if required.
  2. If there is a tests.js file in the polyfill's directory, and the new version has added support for more of the native feature, add tests to cover it in the tests.js file.
  3. Run grunt updatelibrary to install the new version of the library
  4. Run grunt ci to check that library still passes our continuous integration tests. For help connecting to a Sauce Labs account, see running tests on Sauce Labs.
  5. Open a pull request, stating the version of the polyfill you are changing, noting any functional changes that the new version brings
  6. State your agreement to our contribution terms.

A polyfill is not correctly/completely emulating the missing feature

You want to improve a polyfill to make it better emulate the relevant native feature.

  1. If the polyfill's config.json has a repo or install property, then it is a third party dependency. Raise your change with the upstream project and then update it in the polyfill service (see above). Otherwise...
  2. Make your change to the polyfill.js file
  3. Add tests for your new functionality in tests.js (these should fail without your changes to polyfill.js, and pass afterwards)
  4. Run grunt ci to check that library still passes our continuous integration tests. For help connecting to a Sauce Labs account, see running tests on Sauce Labs.
  5. Open a pull request, with a description of the deficiency of the polyfill and how you've fixed it. Ideally link to spec documentation that specifies the behaviour that you are correcting. Finally, tell us how this aspect of the feature is treated in native implementations (so, for example if you can correct a polyfill to acheive better conformance to the spec but this then deviates from how all browsers have consistently implemented it natively, we'll probably prefer to respect the implementation rather than the spec)
  6. State your agreement to our contribution terms.