From 4b1a9203c547c019fc5398082ae19a3f3d4c3efe Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:41:15 -0500 Subject: initial commit --- files/de/mdn/structures/index.html | 10 + .../kompatibilitaets_tabellen/index.html | 500 +++++++++++++++++++++ 2 files changed, 510 insertions(+) create mode 100644 files/de/mdn/structures/index.html create mode 100644 files/de/mdn/structures/kompatibilitaets_tabellen/index.html (limited to 'files/de/mdn/structures') diff --git a/files/de/mdn/structures/index.html b/files/de/mdn/structures/index.html new file mode 100644 index 0000000000..f8ea007204 --- /dev/null +++ b/files/de/mdn/structures/index.html @@ -0,0 +1,10 @@ +--- +title: Document structures +slug: MDN/Structures +translation_of: MDN/Structures +--- +
{{MDNSidebar}}
{{IncludeSubnav("/en-US/docs/MDN")}}
+ +

Throughout MDN, there are various document structures that are used repeatedly, to provide consistent presentation of information in MDN articles. Here are articles describing these structures, so that, as an MDN author, you can recognize, apply, and modify them as appropriate for documents you write, edit, or translate.

+ +

{{LandingPageListSubPages()}}

diff --git a/files/de/mdn/structures/kompatibilitaets_tabellen/index.html b/files/de/mdn/structures/kompatibilitaets_tabellen/index.html new file mode 100644 index 0000000000..758d450e7c --- /dev/null +++ b/files/de/mdn/structures/kompatibilitaets_tabellen/index.html @@ -0,0 +1,500 @@ +--- +title: Kompatibilitäts Tabellen +slug: MDN/Structures/Kompatibilitaets_Tabellen +tags: + - Browser Kompatibilität +translation_of: MDN/Structures/Compatibility_tables +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/en-US/docs/MDN")}}
+ +

MDN hat ein Standard Format für Kompatibilitätstabellen für unsere Offenes Web Dokumentation; Das beeinhaltet die Dokumentation von Technologien, wie zum Beispiel, DOM, HTML, CSS, JavaScript, SVG und viele weitere, welche in jedem Browsern verwendet werden. Dieser Artikel bearbeitet, wie unsere Features verwendet werden sollen um Kompatibilitätsdaten zu den MDN Seiten hinzuzufügen.

+ +
+

Wichtig: Die Art, wie die Daten generiert werden, wurde geändert. Früher wurden unsere Tabellen in die Seite eingefügt und die Daten wurden manuell befüllt. Dies ist Ineffizient, macht die Pflege der Daten schwierig und sorgt für unflexible Daten. Deswegen verschieben wir den Speicher unserer Browserkompatibilitätsdaten in ein Daten Repository (siehe https://github.com/mdn/browser-compat-data) und generieren die Tabellen mit einem Programm.
+
+ In dieser Anleitung dokumentieren wir die neue Art Kompatibilitätsdaten zu MDN hinzuzufügen, aber wir haben die Dokumentation der alten Art immer noch behalten, weil du manuelle Tabellen noch länger auf MDN sehen wirst. Wenn du die alte Dokumentation sehen musst, kannst du unseren Alten Kompatibiltätstabellen Artikel besuchen.

+
+ +
+

Notiz: Wenn du Hilfe zu einem der Schritte dieser Anleitung brauchst, würden wir uns freuen, wenn du uns im MDN Diskussionsforum kontaktierst.

+
+ +

Wie ist das Repository erreichbar?

+ +

Die Daten sind in einem GitHub Repository gespeichert — siehe https://github.com/mdn/browser-compat-data. Um darauf zugreifen zu können, musst du einen GitHub Benutzer erstellen,das browser-compat-data Repository in deinen Account forken, und deinen Fork auf deinen Rechner clonen.

+ +

Wähle ein Feature für das du Daten hinzufügen willst

+ +

Such dir zuerst ein Feature aus, zu dem du Browser-Kompatibilitäts-Daten hinzufügen willst. Das könnte, zum Beispiel ein HTML-Element, eine CSS-Eigenschaft, ein JS-Sprachen-Feature oder ein JS-API-Schnittstelle sein. Wir würden uns wünschen, dass du an API Features arbeitest, da wir bereits Leute haben, die an HTML, JS und CSS arbeiten. Du findest den Status eines Features, für das noch Daten auf das Repository hinzugefügt werden müssen, auf unserer Browser-Kompatibilitäts-Daten Verschiebungstabelle.

+ +

Der Ablauf für das Hinzufügen von Browser-Kompatibilitäts-Daten lautet:

+ +
    +
  1. Öffne die Tabelle und wähle ein Feature an dem nicht schon gearbeitet wird oder bereits übertragen wurde. Schreibe deinen Namen in die "Who" Spalte, wir bevorzugen deinen MDN Nutzernamen, damit wir dich, falls notwendig, über deine E-Mail-Adresse kontaktieren können.
    2. +
  2. Falls das Feature, an dem du Arbeiten willst noch nicht in der Tabelle ist, füge eine Zeile unter Verwendung mit dem gleichen Format und Bennenung ein (z.B. Getrennte Zeilen für unterschiedliche HTML-Elemente, CSS-Eigenschaften, CSS-Selectoren, JS-Objekt und Schnittstellen einer API).
    3. +
  3. Sobald du an einem Feature arbeitest, ändere den Status auf "In progress".
    4. +
  4. Sobald du daten hinzugefügt hast und einen Pull Request zum Main Repo gestellt hast, setze den Status auf "PR done".
    5. +
  5. Wenn deine Daten in das Repo gemerged und zum npm Package hinzugefügt wurden, ändere den Status dementsprechend.
    6. +
  6. Sobald du die Dokumentations-Seite(n) das neue Makro angegeben hast, damit die aktualisierten Tabellen generiert werden, setze den Status auf "Article updated". Damit ist deine Arbeit abgeschlossen.
    7. +
+ +

Preparing to add the data

+ +

Before adding some new data, you should make sure that your fork is up-to-date with the main repo (it contains the same content), create a new branch inside your fork to contain your additions, then pull that branch into your local clone so you can start working inside it:

+ +

Let's look at a simple way to make sure your fork is to-to-date is as follows:

+ +

Adding the main browser-compat-data repo as a remote

+ +

Go to your local clone of your fork in your terminal/command line, and add a remote pointing to the main (upstream) repo like so (you only need to do this once):

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

If you are unsure whether you've done this, you can check what remotes your repo has using

+ +
git remote -v
+ +

Updating your fork with the remote's content

+ +

Now, whenever you want to update your fork, you can do so by:

+ +
    +
  1. +

    Making sure you are in the master branch:

    + + 
    git checkout master
    +
    2. +
  2. +

    fetching the up-to-date repo contents using the following:

    + + 
    git fetch upstream
    +
    3. +
  3. +

    rebasing the contents of your master with the main repo's contents:

    + + 
    git rebase upstream/master
    +
    4. +
  4. +

    pushing these updates back to your remote fork using this:

    + + 
    git push -f
    +
    5. +
+ +

Creating a new branch to do your work in

+ +

Next, go to your remote fork (it will be at https://github.com/your-username/browser-compat-data) and create a new branch to store your changes for this data addition. This can be done by:

+ +
    +
  1. Clicking on the "Branch: Master" button.
    2. +
  2. Entering a new branch name into the "Find or create a branch..." text field.
    3. +
  3. Pressing the resulting "Create branch name-of-branch from Master" button.
    4. +
+ +

For example, if you were wanting to add data for the WebVR API, you'd create a branch called something like "webvr".

+ +

Switching to the new branch

+ +

At this point, go back to your terminal/command line, and update your fork's local clone to include your new branch using the following command:

+ +
git pull
+ +

Now switch to your new branch using this:

+ +
git checkout name-of-branch
+ +

You should now be ready to start adding your data!

+ +

Adding the data

+ +

To add the data, you need to create a new file or files to store your compat data in. The files you need to create differ, depending on what technology you are working on:

+ + + +
+

Note: You'll notice that the repo also contains data for Browser Extensions and HTTP. These data sets are basically finished as they stand, but more features may need to be added in the future.

+
+ +

Each file you create has to follow the pattern defined in the schema contained within our repo; you can see the detailed schema description here.

+ +

Basic compat data structure

+ +

Let's look at an example. CSS property JSON files for example need the following basic structure:

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

You have the css object, inside of which is a properties object. Inside the properties object, you need one member for each of the specific features you want to define the compat data for. Each of these members has a __compat member, inside of which the actual data goes.

+ +

The above data is found in the border-width.json file — compare this to the rendered border-width support table on MDN.

+ +

Other types of features work in the same way, but with different object names:

+ + + +
+

In HTML, CSS, and JS pages, you'll normally only need one feature. API interfaces work slightly differently — they always have multiple sub-features (see {{anch("Sub-features")}}, below).

+ +

Basic structure inside a feature

+ +

Inside a feature __compat member, you need to include the following members:

+ + + +

The names of the browser members are defined in the schema (see Browser identifiers). You should use the full list of currently defined identifiers. If you wish to add another browser, talk to us first, as this could have a wide-ranging impact and should not be done without careful thought.

+ +

In a basic browser compat data file, you'll only need to include "version_added" inside the browser identifier members (we'll cover {{anch("Advanced cases")}} later on). The different values you might want to include are as follows:

+ + + +

Inside the status member, you'll include three submembers:

+ + + +

The feature data for border-width (also see border-width.json) is shown below as an example:

+ +
"__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
+  }
+}
+ +

Adding a description

+ +

There is a fourth, optional, member that can go inside the __compat member — description. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so:

+ +
{
+  "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:

+ +
"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:

+ + + +

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

+ +
"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 {{cssxref("border-top-right-radius")}} property (see also border-top-right-radius.json) was supported in Firefox:

+ + + +

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:

+ + + +

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

+ +
+ + +

{{Compat("api.VRDisplay.capabilities")}}

+ +
+

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.

+
-- cgit v1.2.3-54-g00ecf