<commit_before>{{>header}}

{{>nav this}}

	<div class="o-techdocs-main o-techdocs-content">

		<h1>Authoring polyfills</h1>

		<p>Polyfills are located in the <code>/polyfills</code> directory and organised by feature name.</p>

		<h2 id='naming'>Naming</h2>

		<p>Polyfill directories should be named after their main JavaScript global, and nested subdirectories should be used to descend through objects, e.g. <code>/polyfills/Array/prototype/forEach</code> should be used to hold the polyfill for <code>Array.prototype.forEach</code>.</p>

		<p>Where a polyfill exposes multiple globals, consider splitting it if possible, but if that's not practical, name the polyfill after the most well known of the globals.</p>

		<p>If a feature has no JavaScript API, e.g. support for CSS styling of HTML5 elements, it should be given a descriptive name prefixed with a tilde (~), ie. <code>~html5-elements</code>.</p>

		<h2 id='files'>Files</h2>

		<p>Each polyfill directory (and subdirectory) is structured like this:</p>

		<ul>
			<li><code>polyfill.js</code>: Required. Code to apply the polyfill behaviour.  See <a href="#configuration">configuration</a>.</li>
			<li><code>detect.js</code>: A single expression that returns true if the feature is present in the browser (and the polyfill is therefore not required), false otherwise.  Can be an IIFE.  If not present, polyfill cannot be gated (wrapped in a feature-detect).  <strong>Must not have a trailing semicolon</strong>.</li>
			<li><code>tests.js</code>: A set of tests written using <a href="http://mochajs.org/">mocha</a> and <a href="https://github.com/LearnBoost/expect.js/">expect</a>, to test the feature.  See <a href="#test-authoring-guidelines">test authoring guidelines</a>.</li>
			<li><code>update.task.js</code>: Optional alternative to <code>polyfill.js</code>. This file is used in combination with the Grunt task <code>updatelibrary</code> to create a local copy of an external polyfill.</li>
			<li><code>config.json</code>: A config file conforming to the spec below</li>
		</ul>

		<h2 id='configuration'>Configuration</h2>

		<p>The config.json file may contain any of the following keys:</p>

		<ul>
			<li><code>browsers</code>: Object, one key per browser family name (see <a href="#browsers">browser support</a>), with the value forming either a range or a list of specific versions separated by double pipes, identifying the versions to which the polyfill <em>should be applied</em>. We support all valid <a href="https://github.com/npm/node-semver#ranges">node-semver ranges</a>, but discourage the use of the `<=` operator as it tends to cause confusion.</li>
			<li><code>aliases</code>: Array, a list of alternate names for referencing the polyfill.  In the example Modernizr names are explicitly namespaced.</li>
			<li><code>dependencies</code>: Array, a list of canonical polyfill names for polyfills that must be included prior to this one.</li>
			<li><code>license</code>: String, an <a href="https://spdx.org/licenses/">SPDX</a> identifier for an <a href="http://opensource.org/licenses/alphabetical">OSI Approved</a> license  (Or CC0 which is GPL compatible)</li>
			<li><code>repo</code>: String, the URL of the repository containing the canonical version of the polyfill, of which the version stored in the polyfills library is a copy.</li>
			<li><code>spec</code>: String, the URL of a document that is the canonical technical definition of the feature (ie. the spec, preferably with fragment referencing the specific heading)</li>
			<li><code>docs</code>: String, the URL of an online resource with the most helpful description of the feature for developers (e.g. MDN)</li><commit_msg>Add abbr tag to IIFE<commit_after>{{>header}}

{{>nav this}}

	<div class="o-techdocs-main o-techdocs-content">

		<h1>Authoring polyfills</h1>

		<p>Polyfills are located in the <code>/polyfills</code> directory and organised by feature name.</p>

		<h2 id='naming'>Naming</h2>

		<p>Polyfill directories should be named after their main JavaScript global, and nested subdirectories should be used to descend through objects, e.g. <code>/polyfills/Array/prototype/forEach</code> should be used to hold the polyfill for <code>Array.prototype.forEach</code>.</p>

		<p>Where a polyfill exposes multiple globals, consider splitting it if possible, but if that's not practical, name the polyfill after the most well known of the globals.</p>

		<p>If a feature has no JavaScript API, e.g. support for CSS styling of HTML5 elements, it should be given a descriptive name prefixed with a tilde (~), ie. <code>~html5-elements</code>.</p>

		<h2 id='files'>Files</h2>

		<p>Each polyfill directory (and subdirectory) is structured like this:</p>

		<ul>
			<li><code>polyfill.js</code>: Required. Code to apply the polyfill behaviour.  See <a href="#configuration">configuration</a>.</li>
			<li><code>detect.js</code>: A single expression that returns true if the feature is present in the browser (and the polyfill is therefore not required), false otherwise.  Can be an <abbr title="Immediately Invoked Function Expression">IIFE</abbr>.  If not present, polyfill cannot be gated (wrapped in a feature-detect).  <strong>Must not have a trailing semicolon</strong>.</li>
			<li><code>tests.js</code>: A set of tests written using <a href="http://mochajs.org/">mocha</a> and <a href="https://github.com/LearnBoost/expect.js/">expect</a>, to test the feature.  See <a href="#test-authoring-guidelines">test authoring guidelines</a>.</li>
			<li><code>update.task.js</code>: Optional alternative to <code>polyfill.js</code>. This file is used in combination with the Grunt task <code>updatelibrary</code> to create a local copy of an external polyfill.</li>
			<li><code>config.json</code>: A config file conforming to the spec below</li>
		</ul>

		<h2 id='configuration'>Configuration</h2>

		<p>The config.json file may contain any of the following keys:</p>

		<ul>
			<li><code>browsers</code>: Object, one key per browser family name (see <a href="#browsers">browser support</a>), with the value forming either a range or a list of specific versions separated by double pipes, identifying the versions to which the polyfill <em>should be applied</em>. We support all valid <a href="https://github.com/npm/node-semver#ranges">node-semver ranges</a>, but discourage the use of the `<=` operator as it tends to cause confusion.</li>
			<li><code>aliases</code>: Array, a list of alternate names for referencing the polyfill.  In the example Modernizr names are explicitly namespaced.</li>
			<li><code>dependencies</code>: Array, a list of canonical polyfill names for polyfills that must be included prior to this one.</li>
			<li><code>license</code>: String, an <a href="https://spdx.org/licenses/">SPDX</a> identifier for an <a href="http://opensource.org/licenses/alphabetical">OSI Approved</a> license  (Or CC0 which is GPL compatible)</li>
			<li><code>repo</code>: String, the URL of the repository containing the canonical version of the polyfill, of which the version stored in the polyfills library is a copy.</li>
			<li><code>spec</code>: String, the URL of a document that is the canonical technical definition of the feature (ie. the spec, preferably with fragment referencing the specific heading)</li>
			<li><code>docs</code>: String, the URL of an online resource with the most helpful description of the feature for developers (e.g. MDN)</li>
{'fraction_non_alphanumeric': 0.12385814078452445, 'fraction_numerical': 0.002955400322407308, 'mean_word_length': 4.7093558282208585, 'pattern_counts': {'":': 0, '<': 215, '<?xml version=': 0, '>': 217, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '662258', 'n_tokens_mistral': 2272, 'n_tokens_neox': 2108, 'n_words': 871}