DOCSEARCHbyAlgolia
Submit Docs

MDN Browser Compatibility Data (BCD)

repository·main·Indexed 26 days ago

https://github.com/mdn/browser-compat-data

Machine-readable compatibility data for Web technologies, including Web APIs, CSS, HTML, and JavaScript runtimes. Used by MDN Web Docs, CanIUse, and IDEs, this project provides guidelines for recording browser support, versioning rules for Safari and Chrome, and criteria for marking features as experimental, deprecated, or partially implemented.

Tokens
17.6K
Snippets
35
Records
112
Agent score
90%

What's inside browser-compat-data

  1. Use experimental utilities for compat data

    main

    The utils directory contains experimental utilities designed for working with browser compatibility data. These modules are intended to inform future API developments but are NOT included in the released @mdn/browser-compat-data package.

    Warning:

    • These utilities are NOT covered by the project's Semantic Versioning policy.
    • Backwards compatibility is not assured.
    • Use them only for experimentation and testing purposes.

  2. Understand roles and responsibilities in BCD

    main

    The @mdn/browser-compat-data (BCD) project operates with a tiered community structure. Understanding your role helps you navigate how to contribute and how decisions are made:

    • Users: Consumers of the compat data. Contributions include evangelizing the project or providing feedback on data strengths/weaknesses.
    • Contributors: Individuals who submit data updates, code, or documentation via pull requests. They have read-only access to the source and require review from Peers or Owners.
    • Peers: Experienced community members with push/write access. They can merge compat data and browser data updates, label/close issues, and merge PRs that fix failing tests. Non-data updates (schema, infrastructure, etc.) require Owner review.
    • Owners: The governing group responsible for technical direction, project governance, contribution policy, and releasing npm versions. They have final authority over the project.

  3. Understand the @mdn/browser-compat-data release automation

    main

    The release process is automated using two primary GitHub workflows triggered by the release pull request:

    1. release-pr workflow

    This workflow manages the creation of the release pull request. It runs npm run release and performs the following:

    • Fetches the latest main branch.
    • Determines the previous release version.
    • Determines the version bump type (major or minor) based on whether pull requests with semver-major-bump or semver-minor-bump labels were merged.
    • Updates package.json using npm version.
    • Updates RELEASE_NOTES.md using repository statistics and a list of added/removed features derived from merged pull requests.
    • Commits and pushes changes to the release branch.
    • Creates or updates the release pull request.

    2. release workflow

    Triggered automatically when the release pull request is merged. It performs these steps:

    • create-release job: Creates a GitHub release and tag based on package.json and the release notes.
    • publish-release job:
      • Builds the release.
      • Publishes the release to NPM.
      • Adds data.json as an asset to the GitHub release.
      • Dispatches a bcd_release event to the mdn/bcd-utils repository to trigger MDN deployment.

  4. Locate compatibility data by category

    main

    Compatibility data is organized into top-level directories based on the technology area. You can find specific data in the following directories:

    • api/: Web API interfaces.
    • css/: CSS properties, selectors, and at-rules.
    • html/: HTML elements, attributes, and global attributes.
    • http/: HTTP headers, statuses, and methods.
    • javascript/: JavaScript built-in Objects, statements, operators, and ECMAScript language features.
    • manifests/: Various manifests (e.g., Web Application Manifest).
    • mathml/: MathML elements, attributes, and global attributes.
    • mediatypes/: Media types (MIME types).
    • svg/: SVG elements, attributes, and global attributes.
    • webdriver/: WebDriver commands.
    • webextensions/: WebExtensions JavaScript APIs and manifest keys.
    • webassembly/: Web Assembly features.

  5. Understand the @mdn/browser-compat-data JSON structure

    main

    The published @mdn/browser-compat-data package provides a data.json file that combines browser definitions, feature compatibility data, and metadata.

    Top-level properties include:

    • __meta: Metadata about the dataset (version and timestamp).
    • browsers: Data for all browsers and JavaScript runtimes.
    • Feature categories: Trees of feature identifiers containing __compat objects, including api, css, html, http, javascript, manifests, mathml, mediatypes, svg, webassembly, webdriver, and webextensions.
    {
  "__meta": {
    "version": "6.0.0",
    "timestamp": "2024-01-15T00:00:00.000Z"
  },
  "browsers": {
    "firefox": {
      "name": "Firefox",
      "type": "desktop",
      "releases": {
        "1.5": {
          "release_date": "2005-11-29",
          "status": "retired"
        }
      }
    }
  },
  "api": {
    "AbortController": {
      "__compat": {
        "support": {
          "chrome": { "version_added": "66" }
        }
      }
    }
  }
}

  6. Become a Peer in the BCD project

    main

    To be nominated as a Peer, you must demonstrate commitment and trustworthiness through significant contributions (PRs or reviews).

    Requirements to complete the process:

    1. Show alignment with the project's objectives and strategy.
    2. Read and agree to the Mozilla Commit Access Requirements.
    3. File an issue in the mdn/mdn repository with the exact text: I have read, and agree to abide by, the Mozilla Commit Access Requirements.

    New Peers are nominated by existing Peers and must be approved by a vote of the Owners.

  7. Document Dictionaries and Enumerations (enums)

    main
    Dictionaries and enums in Web IDL are used to define reusable properties. Since they are not directly observable by developers, do not create separate entries for them. Instead, add dictionary members and enum values directly to the appropriate methods and properties as parameter object features.

  8. Check for platform-specific availability in Firefox

    main

    To determine if a feature is available on specific platforms (like Android) versus desktop:

    • Inspect Bug Tests: Look at the C++ tests for the feature's bug. If you see skip-if = toolkit == 'android' or skip-if = os == 'android', the feature is likely unavailable on Android.
    • Check Source Location:
      • Features in dom/ or low-level directories are usually available on both desktop and Android.
      • Features involving UI that reside in browser/ but lack corresponding files in mobile/ are likely desktop-only.

  9. Handle API members moved up the prototype chain

    main

    When Web IDL interfaces move members from a concrete interface to a parent interface (e.g., moving members from AudioContext to BaseAudioContext), follow these rules:

    1. Version Selection: Use the version when the member was first supported on any concrete interface in the chain, even if it predates the current parent interface.
    2. Partial Implementation: If there are versions where the member was supported on a child interface but not yet on the new parent interface, use partial_implementation and include notes in the BCD entry.
    3. Interface Support: Use the version when the interface itself was first supported. If members existed before the interface was introduced, use partial_implementation and notes for that version range.

  11. Identify Safari feature arrival via WebKit entrypoint

    main

    To determine when a feature was introduced in Safari, you can track its entry point in the WebKit source repository.

    1. Locate the feature's entry point, typically in an IDL file.
    2. Find the WebKit version number at the time of addition by checking Source/WebCore/Configurations/Version.xcconfig or WebCore/Configurations/Version.xcconfig within the repository.
    3. Verify the inclusion by checking the relevant release branches or tags.
    4. If needed, map the WebKit version to a specific Safari version using the mapping in browsers/safari.json.

  12. Create behavioral subfeatures

    main

    Use behavioral subfeatures to record support for nuances or evolutions of a parent feature that lack a natural identifier (unlike CSS properties or API methods).

    Requirements:

    • A behavioral subfeature must have a description.
    • Do not create a subfeature if the support data would be identical across all browsers to the parent feature.
    • For serious bugs affecting a single engine, use partial_implementation instead.

    Common use cases:

    • Contextual support: e.g., css.properties.gap.flex_context vs css.properties.gap.grid_context.
    • Execution context: e.g., api.setTimeout.worker_support.
    • Behavioral evolution: e.g., api.HTMLMediaElement.play.returns_promise (changing from callback to promise).
    • UI evolution: e.g., html.global_attributes.inert.ignores_find_in_page.