MDN a un format standard pour les tables de compatibilité de notre documentation du web ouvert ; c'est-à-dire la documentation de technologies comme le DOM, HTML, CSS, JavaScript, SVG etc. partagées par tous les navigateurs. Cet article explique comment utiliser nos fonctionnalités pour ajouter des données de compatibilité aux pages MDN.

Important : La façon dont les données sont générées a changé. Historiquement, nos tables ont été insérées sur la page et les données ont été renseignées manuellement. Ceci est inefficace, rend la maintenance difficile et rend les données inflexibles. Par conséquent, nous migrons les données de notre navigateur pour les stocker dans un référentiel de données (voir https://github.com/mdn/browser-compat-data) et générer les tables par programme.

Dans ce guide, nous documentons la nouvelle façon d'ajouter des données aux tables de compatibilité pour MDN, mais nous avons conservé la documentation à l'ancienne, car vous pourrez voir des tables manuelles sur MDN pendant un moment. Si vous avez besoin de la documentation ancienne, voyez notre article Anciennes tables de compatibilité.

Note : Si vous avez besoin d'aide sur les étapes de ce guide, n'hésitez pas à nous contacter sur le forum de discussion MDN (en).

Comment accéder au dépôt de données

Les données sont stockées dans un dépôt de GitHub — voir https://github.com/mdn/browser-compat-data. Pour y accéder, vous devez obtenir un compte GitHub, réaliser une branche du browser-compat-data sur votre propre compte, puis cloner votre branche sur votre machine locale.

Choisir une fonctionnalité pour y ajouter des données

Tout d'abord, cherchez une fonctionnalité pour laquelle vous souhaitez ajouter des données de navigateur. Cela peut être un élément HTML, une propriété CSS, une fonctionnalité du langage JS ou une interface d'API JS, par exemple. Nous aimerions vous encourager à travailler sur les fonctionnalités de l'API, car nous avons déjà des personnes travaillant sur HTML, JS et CSS. Vous pouvez trouver le statut des fonctionnalités qui ont besoin de leurs données en ajoutant au dépôt sur notre tableur Browser Compat Data migration (migration des données des tables de compatibilité des navigateurs).

Le processus d'utilisation est le suivant :

  1. Allez-y et choisissez une fonctionnalité qui n'est pas déjà travaillée ou complète. Inscrivez votre nom dans la colonne "Who" (qui), de préférence avec votre nom d'utilisateur MDN afin que nous puissions trouver votre adresse e-mail et vous contacter si nécessaire.
  2. Si la fonctionnalité sur laquelle vous souhaitez travailler n'est pas déjà répertoriée dans la feuille de calcul, ajoutez-y des lignes à un emplacement approprié, en copiant le format qui s'y trouve déjà. Vous devez également utiliser la même granularité (par exemple, par élément pour HTML, par propriété ou sélecteur pour CSS, par objet pour JS, par interface pour API).
  3. Une fois que vous avez commencé à ajouter des données, mettez le statut "In progres" (En cours).
  4. Une fois que vous avez ajouté les données et soumis une demande d'extraction au dépôt principal, attribuez le statut "PR done".
  5. Au fur et à mesure que vos données sont fusionnées au rapport, ajoutées au paquet npm, mettez à jour le statut si nécessaire.
  6. Une fois que vous avez mis à jour les pages de documentation pour votre fonctionnalité afin d'utiliser la nouvelle macro pour générer dynamiquement la table de données appropriée sur chaque page, définissez l'état sur "Article mis à jour". À ce stade, vous avez terminé.

Préparation à l'ajout de données

Avant d'ajouter de nouvelles données, vous devez vous assurer que votre branche est à jour avec le dépôt principal (le même contenu), créer une nouvelle branche dans votre embranchement pour contenir vos ajouts, puis récupérer cette branche dans votre clone local pour pouvoir commencer à y travailler :

Regardons un moyen simple de nous assurer que votre fourche est à jour :

Ajout d'un "remote" au dépôt principal navigateur-compat-données

Accédez à votre clone local de la branche dans votre terminal / ligne de commande, et ajoutez un"remote" pointant vers le dépôt principal (en amont) comme ceci (vous n'avez besoin de le faire qu'une seule fois):

git remote add upstream https://github.com/mdn/browser-compat-data.git

Si vous n'êtes pas sûr d'y être parvenu, vous pouvez vérifier quels "remotes" votre dépôt utilise.

git remote -v

Mise à jour de votre branche avec le contenu du "remote"

Maintenant, chaque fois que vous voulez mettre à jour votre branche, vous pouvez le faire en :

  1. Vous assurant que vous êtes dans la branche maîtresse :

          git checkout master
  2. Allant chercher le contenu du dépôt à jour avec la commande suivante :

          git fetch upstream
  3. Rebasant le contenu de votre branche maîtresse avec le contenu du dépôt principal :

          git rebase upstream/master    
  4. poussant ces mises à jour de votre branche distante en utilisant ce :

        git push -f
    

Création d'une nouvelle branche pour y travailler

Ensuite, allez sur votre fourche distante (elle doit être à https://github.com/your-username/browser-compat-data) et créer une nouvelle branche pour stocker vos modifications pour cet ajout de données. Ceci peut être fait en:

  1. Cliquant sur le bouton "Branch: Master".
  2. Saisissant le nom de votre nouvelle branche dans le champ texte "Find or create a branch...".
  3. Cliquant sur le bouton "Create branch name-of-branch from Master" qui vient d'être généré.

Par exemple, si vous vouliez ajouter des données pour l'API WebVR, vous devriez créer une branche nommée "webvr".

Aller sur la nouvelle branche

A ce stade, retournez dans votre terminal / ligne de commande, et mettez à jour la copie de votre fourche locale pour inclure votre nouvelle branche en utilisant la commande suivante:

git pull

Maintenant allez sur votre nouvelle branche en utilisant:

git checkout -b name-of-branch

Vous devriez maintenant être prêt à ajouter vos données!

Ajouter les données

Pour ajouter les données, vous devez créer un ou des nouveaux fichiers pour y stocker les données de compatibilité. Les fichiers que vous devez créer diffèrent, selon la technologie sur laquelle vous travaillez:

  • HTML: Un fichier par élément HTML, contenu dans browser-compat-data/html/elements. Le fichier doit être nommé avec le nom de l'élément, tout en minuscules, ex. div.json.
  • CSS: Un fichier par propriété ou sélecteur CSS, contenu dans le répertoire approprié (voir browser-compat-data/css). Le fichier doit être nommé avec le nom de la fonctionnalité, tout en minuscules, ex. background-color.json, ou hover.json.
  • JS: Un fichier par objet JS, contenu dans browser-compat-data/javascript/builtins. Le fichier doit être nommé avec le nom de l'objet, en respectant la casse, ex. Date.json ou InternalError.json.
  • APIs: un fichier par interface contenu dans l'API, mis dans browser-compat-data/api. Chaque fichier doit être nommé avec le nom exact de l'interface, en respectant la casse, ex. L'API WebVR a VRDisplay.json, VRDisplayCapabilities.json, etc.

Note: Vous remarquerez que le dépôt contient aussi des données pour les Extensions de navigateurs et pour HTTP. Ces ensembles de données sont esssentiellement finis en l'état, mais il faudra peut-être ajouter d'autres fonctionnalités à l'avenir.

Chaque fichier que vous créez doit suivre le modèle défini dans le schéma contenu dans notre dépôt; vous pouvez voir la description détaillée du schema ici.

Structure basique des données de compatibilité

Prenons un exemple. Les fichiers JSON de propriété CSS ont par exemple besoin de la structure de base suivante:

{
  "css": {
    "properties": {
      "border-width": {
        "__compat": {
          ...
        }
      }
    }
  }
}

Vous avez l'objet css, à l'intérieur duquel vous avez l'objet properties. A l'intérieur de l'objet properties, vous avez besoin d'un membre pour chacunes des fonctionnalités  dont vous voulez définir les données. Chacun de ces membres a un membre __compat, à l'intérieur duquel les données vont.

Les données ci-dessus se trouvent dans le fichier border-width.jsoncomparez les à la  table de support de border-width disponible sur MDN.

D'autres types de fonctionnalités fonctionnent sur le même principe, mais avec des noms d'objets différents:

  • Les sélecteurs CSS fonctionnent essentiellement de la même manière que les proprités CSS, sauf que la structure de l'objet de plus haut niveau est css.selectors à la place de css.properties. Voir cue.json pour un exemple.
  • Les données HTML fonctionnent essentiellement de la même manière, sauf que la structure de l'objet de plus haut niveau est html.elements. Voir article.json pour un exemple.
  • La structure d'objet de plus haut niveau pour les objets intégrés JS est javascript.builtins; voir Array.json pour un exemple.

Dans les pages HTML, CSS, et JS, vous n'avez normalement besoin que d'une seule fonctionnalité. Les interfaces d'API fonctionnent légèrement différement — elles ont toujours de multiples sous caractéristiques (voir Sub-features, ci-dessous).

Structure de base à l'intérieur d'une fonctionnalité

Dans un membre __compat, vous devez inclure les membres suivants:

  • mdn_url: Contient l'URL de la page de référence pour cette fonctionnalité sur MDN. Notez qu'elle doit être écrit sans le répertoire de la locale, ex. /docs/... et non /docs/en-US/... (ou autre). Il est ajouté par une macro lorsque les données sont mises sur la page, à des fins de localisation.
  • support: Contient des membres indiquant les informations de support du navigateur pour cette fonctionnalité, dans les différents navigateurs que nous souhaitons indiquer.
  • status: Contient des membres indiquant l'état de suivi des normes pour cette fonctionnalité.

Les noms des membres pour le navigateur sont définis dans le schéma (voir Browser identifiers). Vous devez utiliser la liste complète des identifiants actuellement définis. Si vous souhaitez ajouter un navigateur, parlez-nous en d'abord, car cela pourrait avoir un impact important et ne devrait pas être fait sans une réflexion approfondie.

Dans un fichier de base de compatibilité de navigateur, vous n'avez qu'à inclure "version_added" dans les membres de l'identifiant de navigateur (nous reviendrons plus tard sur Advanced cases). Les différentes valeurs que vous pouvez inclure sont les suivantes:

  • Un numéro de version: Si vous connaissez la version exacte à partir de laquelle le navigateur supporte cette fonctionnalité, utilisez une chaîne de caractères représentant ce nombre, ex. "47".
  • true: Si un navigateur supporte la fonctionnalité mais que vous ne connaissez pas la version exacte, utilisez la valeur true. Ceci équivaut à l'appel de la macro  {{CompatVersionUnknown}} dans les anciennes tables manuelles.
  • false: Si un navigateur ne supporte pas la fonctionnalité, utilisez la valeur false. Ceci équivaut à l'appel de la macro {{CompatNo}} dans les anciennes tables manuelles.
  • null: Si vous ne savez pas si un navigateur supporte ou non une fonctionnalité, utilisez la valeur null. Ceci équivaut à l'appel de la macro {{CompatUnknown}} dans les anciennes tables manuelles.

A l'intérieur du membre status, vous inclurez trois sous-membres:

  •  "experimental": Ceci doit être mis à true si la fonctionnalité est expérimentale, ou false dans les autres cas.
  • "standard_track": Ceci doit être mis à true si la fonctionnalité est en cours de standardisation (le plus souvent W3C/WHATWG, mais il y a aussi d'autres efforts de standardisation tels que Khronos, TC39, etc.) ou false dans les autres cas.
  • "deprecated": Ceci doit être mis à true si la fonctionnalité est dépréciée, ou false dans les autres cas.

Les données pour la propriété border-width (voir aussi border-width.json) sont présentées ci-dessous à titre d'exemple:

"__compat": {
  "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width",
  "support": {
    "chrome": {
      "version_added": "1"
    },
    "webview_android": {
      "version_added": "2"
    },
    "edge": {
      "version_added": true
    },
    "edge_mobile": {
      "version_added": true
    },
    "firefox": {
      "version_added": "1"
    },
    "firefox_android": {
      "version_added": "1"
    },
    "ie": {
      "version_added": "4"
    },
    "ie_mobile": {
      "version_added": "6"
    },
    "opera": {
      "version_added": "3.5"
    },
    "opera_android": {
      "version_added": "11"
    },
    "safari": {
      "version_added": "1"
    },
    "safari_ios": {
      "version_added": "3"
    }
  },
  "status": {
    "experimental": false,
    "standard_track": true,
    "deprecated": false
  }
}

Ajouter une description

Il y a un quatrième membre, optionnel, qui peut être placé à l'intérieur du membre __compat — description. Ceci peut être utilisé pour inclure une description, compréhensible par les humains, de cette fonctionnalité. Vous ne devez l'inclure que s'il est difficile de voir de quoi il s'agit en ne regardant que les données. Par exemple, il peut ne pas être évident qu'il s'agit d'un constructeur en ne regardant que la structure des données, vous pouvez donc ajouter une description comme:

{
  "api": {
    "AbortController": {
      "__compat": {
        ...
      },
      "AbortController": {
        "__compat": {
          "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController",
          "description": "<code>AbortController()</code> constructor",
          "support": {
            ...
          }
        }
      }

      ... etc.
    }
  }
}

Sub-features

In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was addded much later in the specification's life and is only supported in a couple of browsers.

As an example, see the compat data and corresponding MDN page for the background-color property. The basic support exists inside the __compat object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own __compat object.

{
  "css": {
    "properties": {
      "background-color": {
        "__compat": {
          ...
        },
        "alpha_ch_for_hex": {
          "__compat": {
            ...
          },
        }
      }
    }
  }
}

For an API, you've got the top two levels defined as api.name-of-the-interface, then a top-level __compat section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this:

{
  "api": {
    "VRDisplay": {
      "__compat": {
        ...
      },
      "cancelAnimationFrame": {
        "__compat": {
          ...
        }
      },
      "capabilities": {
        "__compat": {
          ...
        }
      },

      ... etc.
      
    }
  }
}

See VRDisplay.json for a full example.

Adding data: Advanced cases

There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data.

Including a footnote

Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for VRDisplay.capabilities (see also VRDisplay.json)  (at the time of writing) had a footnote "Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this:

"chrome_android": {
  "version_added": true,
  "notes": "Currently supported only by Google Daydream."
}

Including a vendor prefix

If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. imagine you had a feature that was supported with a -moz- prefix in Firefox. To specify this in the compat data, you'd need to add a "prefix" submember inside the relevant "firefox" submember. It would look something like this:

"firefox": {
  "version_added": true,
  "prefix": "-moz-"
}

Including browser preferences or flags

Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag.

To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members:

  • "type": The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using about:config in Firefox, or chrome://flags in Chrome), but you might also sometimes use a value of "compile_flag", which is a preference set when the browser build is compiled.
  • "name": This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in chrome://flags.
  • "value_to_set": This is a string representing the value that needs to be set on the preference, for example "true".

So to add a preference/flag to the Chrome support for a feature, you'd do something like this:

"chrome": {
  "version_added": "50",
  "flags": [
    {
      "type": "preference",
      "name": "Enable Experimental Web Platform Features",
      "value_to_set": "true"
    }
  ]
},

If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:

"firefox": {
  "version_added": "57",
  "flags": [
    {
      "type": "preference",
      "name": "dom.streams.enabled",
      "value_to_set": "true"
    },
    {
      "type": "preference",
      "name": "javascript.options.streams",
      "value_to_set": "true"
    }
  ]
},

Including a version where support was removed

Sometimes a feature will be added in a certain browser version, but then removed again as the feature is deprecated. This can be easily represented using the "version_removed" submember, which takes as its value a string representing the version number it was removed on. For example:

"firefox": {
  "version_added": "35",
  "version_removed": "47",
},

Including multiple support points for the same browser entry

Sometimes you'll want to add multiple support data points for the same browser inside the same feature.

As an example, the text-align-last property (see also text-align-last.json) was added to Chrome in version 35, supported behind a pref.

The support mentioned above was then removed in version 47; also in version 47, support was added for text-align-last enabled by default.

To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object:

"chrome": [
  {
    "version_added": "47"
  },
  {
    "version_added": "35",
    "version_removed": "47",
    "flags": [
      {
        "type": "preference",
        "name": "Enable Experimental Web Platform Features",
        "value_to_set": "true"
      }
    ]
  }
],

Note: You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info.

Including an alternative name

Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized.

To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member.

Note: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.

Let's look at an example. The border-top-right-radius property (see also border-top-right-radius.json) was supported in Firefox:

  • From version 4 onwards with the standard name border-top-right-radius.
  • From version 49 onwards with a -webkit- prefix, for browser compatibility purposes.
  • From version 1 onwards with the alternative name -moz-border-radius-topright. Support for this alias was removed in version 12.

To represent this in the data, we used the following JSON:

"firefox": [
  {
    "version_added": "4",
    "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0."
  },
  {
    "prefix": "-webkit-",
    "version_added": "49",
    "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>."
  },
  {
    "alternative_name": "-moz-border-radius-topright",
    "version_added": "1",
    "version_removed": "12"
  }
],

Pushing a change back to the main repo

Once you are finished with adding your compat data, you should first test it using the following commands:

  • npm run lint — tests all the compat data to make sure the JSON is valid, and is written in the correct style, for example correct indentation, no missing commas, etc. It will print out a long list of file names and test results; if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc.
  • npm run show-errors — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used.
  • npm run render 'dotted.path.to.feature' — allows you to preview the markup for the compat table for a data file in the repo. As an example, npm run render 'css.properties.background' shows the table markup for the background property.

If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this:

git add .
git commit -m 'adding compat data for name-of-feature'
git push

Now go to your remote fork (i.e. https://github.com/your-username/browser-compat-data) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen.

At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted.

Inserting the data into MDN pages

Once your new data has been included in the main repo, you can start dynamically generating browser compat tables based on that data on MDN pages using the {{Compat}} macro. This takes a single parameter, the dot notation required to walk down the JSON data and find the object representing the feature you want to generate the compat table for.

Above the macro call, to help other contributors finding their way, you should add a hidden text that is only visible in MDN contributors in edit mode:

<div class="hidden">
<p>The compatibility table on this page is generated from structured data. 
If you'd like to contribute to the data, please check out 
<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 
and send us a pull request.</p>
</div>

As an example, on the Accept-Charset HTTP header page, the macro call looks like this: {{Compat("http.headers.Accept-Charset")}}. If you look at the accept-charset.json file in the repo, you'll see how this is reflected in the JSON data.

As another example, The compat table for the VRDisplay.capabilities property is generated using {{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):


FonctionnalitéChromeEdgeFirefoxInternet ExplorerOperaSafari
Support simple Non15

555

636

Non ? ?
FonctionnalitéAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Support simple Non561 2 3 4 ? ? ? ?6.0

1. Only works in an experimental version of Chrome. (Other builds won't return any devices when Navigator.getVRDisplays() is invoked.)

2. Daydream View supported in Chrome 56.

3. Google Cardboard supported in Chrome 57.

4. From version 56: this feature is behind the WebVR preference. To change preferences in Chrome, visit chrome://flags.

5. Windows support was enabled in Firefox 55.

6. macOS support was enabled in Firefox 63.

Note: The filenames often match the labels given to the interfaces inside the JSON structures, but it is not always the case. When the macro calls generate the tables, they walk through all the files until they find the relevant JSON to use, so the filenames are not critical. Saying that, you should always name them as intuitively as possible.

Étiquettes et contributeurs liés au document

Contributeurs à cette page : wbamberg, jcletousey, loella16
Dernière mise à jour par : wbamberg,