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.

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).

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 :

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):

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

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 :

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:

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:

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:

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:

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.

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

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 {{anch("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 {{anch("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 {{domxref("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:

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:

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:

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

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

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:

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 {{cssxref("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:

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.

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

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:

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:

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:

As an example, on the {{httpheader("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 {{domxref("VRDisplay.capabilities")}} property is generated using \{{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):