Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

На MDN принят стандартный формат таблиц совместимости для нашей открытой веб-документации, то есть документации технологий, таких как DOM, HTML, CSS, JavaScript, SVG и так далее, которые являются общими для всех браузеров. В данной статье описано, как использовать наши возможности по добавлению данных о совместимости на страницы MDN.

Важно: Изменился способ генерации данных. Исторически сложилось, что добавление таблиц на страницы и заполнение их данными осуществлялось вручную. Такой подход неэффективен, затрудняет поддержку и лишает данные гибкости. По этой причине мы перемещаем наши данные по браузерной совместимости в репозиторий (см. https://github.com/mdn/browser-compat-data) и генерируем таблицы программно.

В данном руководстве задокументирован новый способ добавления данных о совместимости в MDN, но мы пока сохранили документацию, описывающую старый способ, так как таблицы, созданные вручную, до сих пор встречаются на MDN. Если вам необходимо заглянуть в старую документацию, обратитесь к статье Старые таблицы совместимости.

Обратите внимание: Если вам потребуется помощь с какими-либо пунктами данного руководства, свяжитесь с нами на форуме MDN.

Как получить доступ к репозиторию

Данные хранятся в репозитории на GitHub — https://github.com/mdn/browser-compat-data. Чтобы получить к нему доступ, необходимо завести учетную запись на GitHub, сделать форк репозитория browser-compat-data в свой аккаунт, а затем склонировать этот форк себе на локальную машину.

Выбор возможности для добавления данных

Сначала найдите возможность, для которой вы хотите добавить данные по совместимости. Это может быть, к примеру, элемент HTML, свойство CSS, особенность языка JavaScript или JS API интерфейс. Нам хотелось бы, чтобы вы работали над возможностями API, поскольку у нас уже есть люди, которые работают над HTML, JS и CSS. Статус возможностей, которые нуждаются в добавлении данных по ним в репозиторий, можно посмотреть в таблице Browser Compat Data migration.

Как это использовать:

  1. Идите и выберите возможность, работа над которой еще не была завершена и в настоящий момент не ведется. Впишите свое имя в столбец "Who" ("Кто"), лучше вместе с названием вашего аккаунта на MDN, – так мы сможем при необходимости найти ваш e-mail и связаться с вами.
  2. Если возможность, над которой вы хотели бы поработать, еще не внесена в таблицу, добавьте под нее строки в подходящем месте, скопировав при этом использующееся форматирование. Кроме того, следует использовать одинаковую степень детализации (например, по элементам в случае HTML, по свойствам или селекторам в случае CSS, по объектам в случае JS, и по интерфейсам в случае API).
  3. Когда вы приступите к работе по добавлению данных, поставьте статус "In progress" ("В работе").
  4. Как только вы добавили данные и отправили пул реквест в основной репозиторий, поставьте статус "PR done" ("PR отправлен").
  5. Обновляйте статус по мере того, как ваши данные будут слиты с основным репозиторием, а затем добавлены в пакет npm.
  6. Когда вы обновили все страницы документации для вашей возможности так, чтобы в них использовался новый макрос для динамической генерации соответствующей таблицы с данными, поставьте статус "Article updated" ("Статья обновлена"). Это заключительный этап работы.

Подготовка к добавлению данных

Перед тем, как добавить новые данные, вы долны убедиться, что ваш форк не отстает от основного репозиторию (имеет одинаковое содержимое), создайте новую ветку внутри своего форка, которая будет содержать ваши добавления, а затем подтяните эту ветку в ваш локальный клон, чтобы начать в ней работать:

Давайте рассмотрим простой способ убедиться, что ваш форк не отстает от основного репозитория:

Добавление основной репозиторий browser-compat-data как удаленный

Перейдите в терминале/командной строке к локальной копии вашего форка и добавьте указание на удаленный основной (upstream) репозиторий (это нужно сделать всего один раз):

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

Если вы не уверены, сработала ли команда, вы можете проверить, какие удаленные репозитории используются в вашей копии следующим образом:

git remote -v

Обновление вашего форка удаленным контентом

Теперь, когда вам будет необходимо обновить ваш форк, вы можете сделать это так:

  1.  Убедитесь, что вы находитесь в главной ветке (master):

    git checkout master
  2. Получите актуальное содержимое репозитория:

    git fetch upstream
  3. Сделайте rebase содержимого вашей ветки master и основного репозитория:

    git rebase upstream/master
  4. Отправьте эти обновления обратно в ваш удаленный форк:

    git push -f

Создание новой ветки для своей работы

Далее, перейдите в ваш удаленный форк (он будет располагаться в https://github.com/ваш-аккаунт/browser-compat-data) и создайте новую ветку для хранения изменений для вашего добавления данных. Это можно сделать следующим образом:

  1. Нажмите на кнопку ""
  2. Введите название новой ветки в текстовое поле "Найти или создать ветку...".
  3. Нажмите на финальную кнопку "".

К примеру, если бы вы собирались добавить данные по WebVR API, вы бы содали ветки с названием в духе "webvr".

Переключение на новую ветку

На этом этапе вернитесь к своему терминалу/командной строке и обновите локальную копию вашего форка, чтобы включить в нее свежесозданную ветку с помощью следующей команды:

git pull

Теперь переключитесь на вашу новую ветку:

git checkout название-ветки

Все готово для того, чтобы начать добавлять данные!

Добавление новых данных

Чтобы добавить данные, вам необходимо создать новый файл (или файлы) для хранения ваших данных по совместимости. Для разных технологий (в зависимости от того, над какой вы ведете работу) вам понадобятся разные файлы:

  • HTML: Отдельный файл на каждый HTML элемент, в папке browser-compat-data/html/elements. Файл должен называться именем элемента, в нижнем регистре, например, div.json.
  • CSS: Отдельный файл в соответствующей директории (см. browser-compat-data/css) на каждое CSS свойство или селектор. Имя файла должно совпадать с именем свойства/селектора, в нижнем регистре, например, background-color.json или hover.json.
  • JS: Отдельный файл на каждый объект JS, в browser-compat-data/javascript/builtins. Файл должен называться в точности так же, как и сам объект, с сохранением регистра, например, Date.json или InternalError.json.
  • API: Отдельный файл на каждый интерфейс из API, в browser-compat-data/api. Каждый файл должен совпадать по названию с интерфейсом, с сохранением регистра, например, в API WebVR есть VRDisplay.json, VRDisplayCapabilities.json, и т.д.

Обратите внимание: Вы заметите, что в репозитории также содержатся данные по Браузерным расширениям и HTTP. Эти наборы данных уже фактически закончены, но, возможно, в будущем возникнет необходимость в добавлениях.

Каждый создаваемый вами файл должен следовать шаблону, описанному в схеме, содержащейся в нашем репозитории. Ознакомиться с подробным описанием схемы вы можете здесь.

Базовая структура данных по совместимости

Давайте рассмотрим пример. JSON файлы для CSS-свойства нуждаются в следующей базовой структуре:

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

Есть объект css, который содержит объект properties. 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:

  • CSS selectors work in basically the same way as CSS properties, except that the top-level object structure is css.selectors instead of css.properties. See cue.json for an example.
  • HTML data works in basically the same way, except that the top-level object structure is html.elements. See article.json for an example.
  • The top level object structure for JS built-in objects is javascript.builtins; see Array.json for an example.

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 Sub-features, below).

 

Правила совместимости

In a perfect world, any time someone updates a compatibility table, they'd research every browser and update new tables or rows in tables with the correct and latest information about every browser in the table. In reality, that's a lot to ask of many volunteer contributors and MDN contributors from other browser organizations (hi there and welcome, by the way!). If you're not able to add correct details for every browser, that's okay—but we do ask that you follow a couple of guidelines that will help make sure that information is added by later contributors.

  • When you need to list multiple versions of a browser in a cell (for instance, the version in which something landed behind a preference, then the version in which it was enabled by default, please put them in oldest-version-first order, for consistency.
  • Please don't simply paste {{CompatNo}} or {{CompatVersionUnknown}} for any browser for which you can't provide correct information. If you don't know the answer, please just put {{CompatUnknown}}. This puts a clear indicator into that browser's column that says that someone should find out the answer and add it. If you put any other value, it could get overlooked, resulting in developers being misinformed.
  • Please don't just leave cells empty. This, too, is confusing, as it can look like you may be in the middle of updating the page. It leaves the table in an ambiguous state in which the entire table may be considered unreliable.

Шаблоны таблиц совместимости

You should copy and paste all the following content into your article (first switching into the editor before copying), starting with the use of the {{CompatibilityTable()}} template and including both of the following tables. The first table contains compatibility information for the desktop versions of browsers, and the second table contains compatibility information for the mobile versions. This should get you all the content, including the required <div> blocks.

Совместимость браузеров

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support ? ? ? ? ?
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? ? ? ? ? ?

Использование таблиц

You should fill out the table with appropriate information for each browser, as known. You may include just the version that introduced support, or you may optionally include additional notes (such as "Introduced in version X as -moz-foo"). Feel free to include links to appropriate additional documentation if needed or appropriate, and be sure to use the templates provided to help keep the look and feel of the version information consistent.

The important thing is to use the {{CompatibilityTable()}} template and then have two <div> blocks, one with the ID "compat-desktop" and one with the ID "compat-mobile", each containing an appropriate table in the format shown above. The tables should use the class "compat-table" to achieve the correct style.

Шаблоны для использования в таблицах совместимости

In order to help standardize appearance, and let us more easily change the look and feel of the tables over time, we have a number of templates you should use in the table cells:

Template:CompatNo
Use {{CompatNo()}} to indicate that the browser does not support the feature at all.
Template:CompatUnknown
Use {{CompatUnknown()}} to indicate that the browser's support for the feature is not known. Hopefully someone who does know will come along and fill this in for you later!
Template:CompatVersionUnknown
Use {{CompatVersionUnknown()}} to indicate that the browser has support for the feature but the earliest version of support is not known. Hopefully someone who does know will come along and fill this in for you later!
Template:CompatNightly
Use {{CompatNightly(browser)}} to indicate that the browser has support for the feature but only in nightly builds. Specify a keyword indicating which browser you're referring to, and the template will insert a link to nightlies for that browser if such nightlies exist.
  • firefox / firefoxmobile
  • chrome / chromemobile
  • ie / iemobile
  • opera / operamobile
  • safari / safarimobile
Nightly links are currently automatically inserted for Firefox, Firefox mobile, Chrome, and Safari. Using CompatNightly for Opera currently provides a link to snapshot.opera.com, which doesn't necessarily offer nightlies but offers developmental snapshots.
Template:CompatGeckoDesktop
Use {{CompatGeckoDesktop(geckoversion)}} to indicate compatibility was introduced in the specified Gecko version on desktop Firefox; we have this special template for Gecko so we can let the template map Gecko versions to Firefox releases, given that they don't always correlate in obvious ways (and the relationship can change over time during development).
Template:CompatGeckoMobile
Use {{CompatGeckoMobile(geckoversion)}} to indicate compatibility was introduced in the specified Gecko version on mobile Firefox; we have this special template for Gecko so we can let the template map Gecko versions to Firefox releases, given that they don't always correlate in obvious ways (and the relationship can change over time during development).
Template:CompatChrome
Use {{CompatChrome(chromeversion)}} to indicate compatibility was introduced in the specified Chrome version.
For prefixed features
Some features are prefixed with a vendor-specific name (such as -moz- or -webkit-) when implemented before the specification is finalized. In order to call attention to the compatibility table in these cases, you should use {{SeeCompatTable()}} at the top of the page. This generates a box explaining this situation, with a link to the compatibility table. The output looks like this:

Это экспериментальная технология
Так как спецификация этой технологии ещё не стабилизировалась, смотрите таблицу совместимости по поводу использования в различных браузерах. Также заметьте, что синтаксис и поведение экспериментальной технологии может измениться в будущих версиях браузеров, вслед за изменениями спецификации.

All templates are tagged with CompatTemplate.

Специфика Webkit тегов

WebKitBug inserts a link to a bug in the WebKit bug database. This makes it easy for writers to add annotations to documentation to guide developers to information about things that are works in progress in WebKit. You use it like this: {{webkitbug(42)}}, and the result is “WebKit bug 42″, linked to the corresponding bug in the bug database.

See MDN for WebKit Writers for more details.

Метки документа и участники

Метки: 
 Внесли вклад в эту страницу: KTatyana, warsan, teoli, Artur
 Обновлялась последний раз: KTatyana,