Публикация адаптера

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

Если адаптер стабильно работает в определенной версии, его можно переместить в стабильный репозиторий. Для этого требуется собственная оценка разработчика с учетом отзывов пользователей.

Дополнительные текущие требования можно найти здесь: https://github.com/ioBroker/ioBroker.repositories/blob/master/README.md

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

  1. Для проверки репозитория адаптера используйте https://adapter-check.iobroker.in/ .

  2. В названии репозитория адаптера на GitHub буква ioBroker должна быть заглавной, тогда как в файле package.json она должна быть строчной, потому чтоnpm Заглавные буквы не допускаются.

  3. В файле io-package.json заголовок не должен содержать это слово.ioBroker и не словоAdapter содержать.

  4. Онtitle Атрибут в файле io-package.json (common) — это сокращенное название адаптера на английском языке. Во времяtitleLang переводыtitle Включены атрибуты. (Расширение "Lang" означает языки.)

  5. Адаптер должен содержать инструкции в виде файла README.md. Они должны быть доступны как минимум на английском языке. Дополнительные языки приветствуются. Этот пример может послужить источником вдохновения.

  6. Для работы адаптера требуется лицензия. Это указано как в файле io-package.json, так и в отдельном файле в репозитории GitHub.

    Пример файла io-package.json:

    {
  "common": {
      "license": "MIT"
  }
}

  7. Онwww каталог, а такжеwidget Каталоги следует удалять, когда они не используются.

  8. Файл io-package.json должен содержатьtype В разделе «Общие» будет создан атрибут. Из этого списка следует выбрать наиболее подходящую категорию.

  9. В файле io-package.json должны содержаться следующие данные:connectionType иdataSource Атрибуты создаются в разделе «Общие». Из этого списка следует выбрать наиболее подходящую категорию подключения.

  10. Состояния, создаваемые адаптером, должны содержать достоверную информацию о своих ролях .role в рамках общего. Использование роли.state Следует избегать.

  11. Адаптер должен запускать тесты из фреймворка через GitHub Actions , как минимум тесты пакетов и интеграционные тесты (т.е., тесты установки и запуска). Рабочие процессы для этого уже включены в Adapter Creator и находятся в соответствующей папке..github/workflows Дополнительную информацию можно найти в разделе «Тесты адаптера» .

Разработчик может расширить область применения теста.

  1. В файле io-package.json должна содержаться как минимум одна запись в разделе common для атрибута.authors Это необходимо сделать. Атрибут также должен быть...author Этот параметр необходимо заполнить в файле package.json. При желании можно указать нескольких авторов для npm, добавив соответствующий атрибут в файл package.json.contributors используется.

  2. Адаптер необходимо опубликовать в виде пакета на npmjs.com . В следующем разделе объясняется, как это сделать.

  3. Организация ioBroker должна быть совладельцем пакета npm :

    npm owner add bluefox iobroker.<adaptername>

    Это не просто формальность. Это гарантирует, что пакет будет продолжать поддерживаться, даже если у разработчика больше не будет на это времени. Без этой записи адаптер не будет включен.

Требования к стабильному репозиторию

  1. Адаптер успешно добавлен в репозиторий "Последние версии".
  2. На форуме есть тема, посвященная тестированию адаптера, в которой уже были оставлены отзывы пользователей.
  3. Необходимо реализовать функцию обнаружения. Это функция внутри адаптера обнаружения , которая автоматически определяет, может ли пользователь использовать экземпляр адаптера. Запрос на добавление этой функции следует отправить в репозиторий адаптера обнаружения .

Опубликовать на npm

Прежде чем адаптер можно будет добавить в репозиторий ioBroker, он должен быть доступен в npm. Администратор получает его оттуда во время установки, а не из GitHub.

В состав фреймворка Adapter Creator входит скрипт выпуска , предназначенный для этой цели:

npm run release patch     # Fehlerbehebungen
npm run release minor     # neue Funktionen, abwärtskompatibel
npm run release major     # Änderungen, die Bestehendes brechen

Эта команда за один шаг выполняет то, что обычно происходит по отдельности: она увеличивает версию в обоих файлах.package.json иio-package.json , переносит изменения из журнала изменений вcommon.news Программа проверяет лицензию, устанавливает тег Git и отправляет все изменения на GitHub.

Рабочий процесс в.github/workflows Затем, как только наступит нужный день, он публикует изменения в npm. Это также можно сделать вручную:

npm publish

Для публикации из GitHub Actions больше не требуется токен npm в репозитории. npm теперь поддерживает доверенную публикацию : пакет связывается с репозиторием GitHub в npm, а аутентификация в процессе осуществляется через OpenID Connect. Это устраняет необходимость в постоянном секретном ключе в настройках репозитория.

После публикации версия является окончательной. Версия на npm не может быть перезаписана, иnpm unpublish Это возможно только в течение первых 72 часов, и даже в этом случае номер версии становится непригодным для использования. Лучше иметь одну запасную версию, чем неработающую в обращении.

Добавление адаптера в официальный репозиторий.

Списки находятся в репозитории ioBroker.repositories . Файлы не редактируются вручную; вместо этого используются скрипты для размещения записи в нужном месте и немедленной проверки.

  1. Создайте форк репозитория и клонируйте его локально.

  2. Сгенерируйте запись:

    npm run addToLatest -- --name <adaptername> --type <kategorie>
npm run addToStable -- --name <adaptername> --version <version>

    Категория — одна из списка ниже ; версия в разделе «Стабильная» — это номер версии, которая должна стабильно работать.

  3. Внесите изменения в файл и отправьте запрос на слияние.

  4. При добавлении проекта в стабильный репозиторий необходимо указать номер версии. Этот номер необходимо обновлять по мере дальнейшей разработки адаптера.

  5. В файле io-package.json адаптер должен иметь атрибут типа list.docs Укажите, где найти инструкции на соответствующем языке. Язык указывается в качестве ключа, а путь к файлу Markdown — в качестве значения. Инструкции на английском языке обязательны (в случае необходимости можно обратиться к стандартному файлу README). Инструкции на немецком языке также желательны, поскольку большая часть пользователей говорит по-немецки, но это необязательно. Подробные инструкции могут сэкономить разработчику много времени на форуме. Пример можно найти здесь .

    Пример:

    {
  "common": {
     "docs": {
         "de": "docs/de/README.md"
     }
  }
}

Последний

Файлsources-dist.json Требуется редактирование:

Пример:

  "admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "published": "2017-04-10T17:10:21.690Z",
    "type": "general"
  }

Онpublished Указанная дата представляет собой дату первой публикации и не подлежит изменению.

Стабильный

Файлsources-dist-stable.json Требуется редактирование:

Пример:

  "admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "version": "2.0.7",
    "published": "2017-04-10T17:10:21.690Z",
    "type": "general"
  }

Онpublished Указанная дата представляет собой дату первой публикации и не подлежит изменению.

Управление версиями адаптеров

Текущий номер версии адаптера указывается как в файле io-package.json, так и в файле package.json. Эти две записи должны совпадать. Номер версии разделяется на три части двумя точками.

"version": "1.7.6"

Где первая часть (слева направо)Major Part представляет собой вторую частьminor Часть и последняяmicro Часть. Номера версий следует увеличивать в соответствии со следующим списком:

  • micro : Были исправлены только ошибки.
  • Незначительное изменение : Добавлены новые функции, но версия совместима с предыдущими версиями.
  • Крупные изменения : Значительные изменения, приводящие к потере обратной совместимости со старыми версиями.

В файл io-package.json также следует включить следующее:news Этот атрибут необходимо поддерживать. Это позволит пользователям устанавливать любую из перечисленных версий (при условии, что она опубликована на npm) через административный интерфейс. Номер версии и внесенные изменения должны быть зафиксированы. Изменения могут быть задокументированы для каждого поддерживаемого языка, но должны быть указаны как минимум на английском языке.

Пример:

"news": {
    "1.7.6": {
        "en": "Configuration dialog was corrected",
        "de": "Konfigurationsdialog wurde korrigiert",
        "ru": "Диалог конфигурации был исправлен",
        "pt": "A caixa de diálogo de configuração foi corrigida",
        "nl": "Configuratiedialoog is gecorrigeerd",
        "fr": "La boîte de dialogue de configuration a été corrigée",
        "it": "La finestra di configurazione è stata corretta",
        "es": "Se corrigió el diálogo de configuración",
        "pl": "Okno dialogowe konfiguracji zostało poprawione"
    },
    "1.7.5": {
        "en": "The roles were tuned",
        "de": "Die Rollen waren abgestimmt",
        "ru": "Роли были настроены",
        "pt": "Os papéis foram afinados",
        "nl": "De rollen zijn afgestemd",
        "fr": "Les rôles ont été réglés",
        "it": "I ruoli erano sintonizzati",
        "es": "Los roles fueron sintonizados",
        "pl": "Role zostały dostrojone"
    }
}

Категории адаптеров

  • alarm - Системы безопасности
  • climate-control - Кондиционеры, воздушные фильтры, обогреватели и многое другое
  • communication - Предоставление данных для других адаптеров, например, через REST.
  • date-and-time - например, календари
  • energy - Мониторинг электропитания, солнечные системы, инверторы и многое другое.
  • metering - Другие системы измерения (например, воды, газа, нефти)
  • garden - например, газонокосилки, системы полива
  • general - Общие адаптеры, такие как Admin, Web, Discovery
  • geoposition - Геолокация объектов или людей
  • hardware — Различное многофункциональное оборудование, такое как Arduino, ESP, Bluetooth и др.
  • health - Артериальное давление, частота сердечных сокращений, масса тела, ...
  • household - Кухонная техника, пылесосы и т. д.
  • infrastructure - Сеть, сетевые хранилища (NAS), принтеры, телефоны
  • iot-systems - Другие системы «умного дома» (аппаратное и программное обеспечение)
  • lighting - Освещение
  • logic - Правила, скрипты, парсеры и т. д.
  • messaging - Адаптер для отправки и получения сообщений, например, по электронной почте, Telegram и т. д.
  • misc-data - Экспорт и импорт данных, конвертер валют и т. д.
  • multimedia - Телевизоры, AV-ресиверы, колонки, голосовые помощники и т. д.
  • network — Пинг, обнаружение сети, UPnP, ...
  • protocols - Протоколы связи, например, MQTT
  • storage - Ведение журналов, хранение данных, например, в реляционных базах данных, ...
  • utility - Поддержка адаптеров, таких как резервные копии.
  • vehicle - Автомобили
  • visualization - Адаптеры визуализации, такие как vis и т. д.
  • visualization-icons - Иконки для визуализации
  • visualization-widgets - iobroker.vis Виджеты
  • weather - Информация о погоде, качестве воздуха, экологическая информация

Тип подключения адаптера

ОпределятьconnectionType вcommon Частьio-package.json как:

  • local - Обеспечивает прямую связь с устройством или концентратором.
  • cloud — Данное устройство интегрировано через облако и требует активного подключения к интернету.

ОпределятьdataSource вcommon как:

  • poll — Проверка статуса означает, что обновление может быть замечено позже.
  • push- ioBroker будет уведомлен, как только появится новый статус.
  • assumption - Невозможно определить состояние устройства. ioBroker определяет состояние на основе последней команды ioBroker.