На 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. Внутри объекта properties вам нужно указать свойство, для которого вы хотите определить данные по совместимости.

Вышеуказанные данные находятся в файле border-width.json — сравните их со сформированной таблицей соместимости для свойства border-width на MDN.

Другие типы данных работают аналогично, но имеют другие имена объектов:

  • CSS селекторы работают в основном также, как и CSS свойства, за исключением того, что на верхнем уровне объекта данных используется css.selectors вместо css.properties. Смотрите пример cue.json.
  • Данные HTML в целом работают аналогично, за исключением того, что объект данных имеет струтктуру html.elements на верхнем уровне. Смотрите пример article.json.
  • Структура верхнего уровня для встроенных объектов JavaScript содержит javascript.builtins; смотрите пример Array.json.

На страницах HTML, CSS и JS, как правило, вам потребуется только одно свойство. Интерфейсы API работают немного по-другому — у них всегда есть несколько дочерних свойств (смотрите Дочерние свойства ниже).

 

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

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.

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

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