Skip to content

Latest commit

 

History

History
262 lines (201 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

262 lines (201 loc) · 10.7 KB

Contributing

We welcome contributions! If you believe that some implementation info should be added, modified, fixed or removed from the list, consider submitting a pull request, taking the considerations below into account. Alternatively, feel free to raise an issue.

Please note the open source data and code license for this project.

Table of Contents

Pre-requisites

To prepare a pull request, please:

  • install Node.js v16.14 or above if not already done,
  • fork this Git repository,
  • install dependencies through a call to npm ci

Implementation info comes for external platform status projects

The implementation information in the index.json file is generated by collecting information external platform status projects:

If the implementation information is incorrect, the information should better be fixed at the source. If that is not possible, or as temporary workaround, there exists an exception mechanism in this project to specify the implementation information manually, see below. This should only be used as last resort.

The actual list is in the data folder

The index.json file is automatically generated by processing the contents of the data folder and mapping its contents to the implementation information collected from external platform status projects.

Each file in the folder is a JSON file with the following structure:

{
  "statusref": {
    "bcd": [
      {
        "id": "bcd.identifier",
        "name": "entry name",
        "statusUrl": "URL on the platform status project",
        "specUrls": [
          "List of spec URLs (with fragments) that the entry is associated with"
        ],
        "representative": true,
        "manual": false
      },
      "additional bcd mappings"
    ],
    "caniuse": [
      "Can I Use mappings"
    ],
    "chrome": [
      "Chrome mappings (note ids are number in that case)"
    ],
    "webkit": [
      "Webkit mappings"
    ],
    "manual": [
      {
        "ua": "user agent identifier",
        "status": "implementation status",
        "source": "feedback or other",
        "date": "YYYY-MM-DD",
        "comment": "Rationale for including this implementation info manually"
      }
    ]
  },
  "features": {
    "feature name": {
      "url": "URL of the section that defines the feature in the spec",
      "title": "Human readable description of the feature",
      "statusref": ["same construct as at the root level"]
    }
  },
  "polyfills": [
    {
      "url": "URL of a polyfill library",
      "label": "Name of the polyfill library"
    }
  ],
  "altUrls": {
    "Alternative (often outdated) URLs that may be used to reference the spec"
  },
  "notes": [
    "Possible notes on this information"
  ]
}

Each file in the data folder must be named after the shortname of the specification series it describes.

statusref

The statusref property creates the mapping between the specification series (or an individual feature) and corresponding entries in external platform status projects.

Object keys must reference one of the supported platform status projects: bcd, caniuse, chrome, webkit. Alternatively, it can be manual to override the info found in platform status projects.

Properties managed automatically

In most cases, mapping objects under th eplatform status project keys are created and (mostly) managed automatically: a job regularly looks at platform status projects and automatically proposes mappings. The properties id, name, statusUrl and specsUrls are typically maintained automatically.

The id is set to a key identifier, which depends on the platform status project:

  • bcd: the hierarchy of strings that identifies the feature in the MDN Browser Compatibility Data, e.g. "api.Navigator.sendBeacon"
  • caniuse: the name of the feature in Can I use (the one that appears in the URL after #feat=), e.g. "accelerometer"
  • chrome: the number used to identify features in Chrome Platform Status (the one that appears in the URL after features/), e.g. 5656221012983808 (note it must be a number, not a string)
  • webkit: the name used to identify features in WebKit Feature Status (the one that appears in the URL after status/#), e.g. "specification-geolocation-api"

The name property is set to the title of the entry on the platform status project, if there is a meaningful title that could be determined. The title serves no real purpose for computing implementation support, it is simply there for human beings to understand what the data is about without having to look up the corresponding page in the platform status project.

The statusUrl property is a URL that targets the corresponding page in the platform status project.

The specsUrl property lists the URLs of the spec(s) with fragments that the platform status project entry relates to. Most of the time, an entry only references one section in a spec, but there are cases where two or more sections are referenced.

representative

The representative flag should be set on entries that are deemed representative of the implementation status of the spec series or feature under consideration. For instance, the 5712361335816192 (Web Locks API) entry on Chrome Status could perhaps be viewed as representative of the implementation status of the Web Locks API in browsers.

This flag needs to be set manually on all entries of that kind.

More than one entry may be flagged as representative. For instance, support for WOFF could be seen as encompassing WOFF 1.0 and WOFF 2.0, meaning that both woff and woff2 should be flagged as representative to compute the implementation status from Can I Use.

manual

The manual flag should be set on entries that the code cannot automatically associated with the spec series under consideration but that should still be preserved.

The job that identifies mappings will actually create a pull request to delete entries that it cannot associated with the spec series... unless it sees a manual flag.

Providing custom implementation status

From time to time, external platform status projects may:

  • contain implementation information about the specification but at a different granularity level, e.g. you want implementation info about the entire specification and the site only gives implementation status about a particular feature within the specification, or the opposite
  • contain implementation information which you know is incorrect.
  • not contain any information about a specification at all

When this happens, you may use the manual sub-property to specify implementation status manually. Property value must be an array of objects that have the following properties:

  • ua: the user agent name (typically one of edge, firefox, chrome, safari, webkit)
  • status: the implementation status, which should be one of shipped, indevelopment, experimental, consideration, or an empty string to say "Not currently considered".
  • source (optional but recommended): a short name that identifies the origin of the information. Use feedback to flag information that comes from review and that should override whatever other implementation status the framework might be able to retrieve automatically for the user agent under consideration.
  • date (optional but recommended): the YYYY-MM-DD date at which that manually information was last reviewed. Keeping implementation information up to date is difficult and error prone. The information needs to be periodically checked and re-validated. The date is meant to track the last time when someone checked and validated the information.
  • comment (optional but recommended): a comment that provides contextual information, for instance to explain why the information in platform status sources should be regarded as incorrect.
  • prefix (optional): whether the implementation requires the use of a prefix
  • flag (optional): whether some flag needs to be set to enable the feature

You should only set properties when there values are meaningful. For instance, no need to include an empty notes property.

features

A list of specific features defined in the specification, indexed by some unique feature identifier. Features are maintained manually.

polyfills

A list of polyfills that may exist

[
  {
    "label": "sensor-polyfills",
    "url": "https://github.com/kenchris/sensor-polyfills"
  }
]

altUrls

A list of alternative (and often outdated) URLs that platform status projects may use to reference the spec. For instance, the wicg.github.io URL of a spec that has since then migrated to a W3C working group. The information is used to find additional mappings.

notes

Possible notes on the data. Intended to ease maintenance.

How to validate data

Automated tests will enforce that files in the data folder follow the appropriate schema. You may run these tests locally, and make sure that the information can be processed correctly through:

npm test
npm run build

No index.json in the pull request

The index.json file will be automatically generated once your pull request has been merged. Please do not include it in your pull request. You may still wish to re-generate the file if you want to check that the generated info will be correct, but please don't commit these changes.