Добавить плагин

В этом документе описывается процесс создания нового плагина. Хотя он относится к созданию собственных плагинов, вы можете использовать его в качестве руководства для создания плагинов сторонних разработчиков.

Обзор плагинов см. в разделе «Плагины» .

Для краткого ознакомления с процессом создания плагина, посмотрите наш доклад «Как создать плагин» (2021) .

Собственная разработка против сторонней разработки

Целевой пользователь плагина — разработчик, который находит и использует плагин через npm.

First-party plugins are supported by the Blockly team and published under the @blockly scope on npm. They are designed to be usable in a wide range of Blockly applications and are stable and easy to use. They are stored in the blockly-samples . A field for setting motor speed could be used in many robotics projects and is a good candidate for a first-party plugin.

Сторонние плагины поддерживаются и публикуются независимо. Они могут быть более сложными, экспериментальными или ориентированными на более узкий круг приложений Blockly. Поле для редактирования конкретного объекта, определенного схемой вашей базы данных, лучше оформить в виде стороннего плагина.

Критерии первой стороны

Собственные плагины должны соответствовать следующим требованиям:

  • Работает на всех основных платформах, за исключением случаев, когда команда Blockly предоставляет исключение.
    • Chrome, Firefox, Safari, Edge
  • Найдите автора, который готов заниматься исправлением ошибок в течение первого года.
  • Не используйте модификаторы для Blockly.
  • Необходимо иметь четко определенный и задокументированный API.
  • Не вызывайте частные или пакетные функции из ядра Blockly, за исключением случаев, когда команда Blockly предоставила вам исключение.
    • Переопределение функций пакета в подклассе, который вы определяете, разрешено.
    • Если вам нужно исключение, сообщите нам об этом в теме на форуме blockly-samples.
  • Пройдите тесты.

Процесс

Разработка плагинов проходит четыре этапа: предложение , обсуждение , внедрение и публикация .

Предположение

Создание плагина начинается с предложения . Вы можете предложить плагин, создав новую задачу с использованием шаблона «Запрос на добавление функции» . Для получения дополнительной информации ознакомьтесь с инструкцией по написанию запроса на добавление функции .

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

  • API, который будет предоставлять плагин.
  • API-интерфейсы, которые необходимо добавить или изменить в ядре Blockly для поддержки плагина.
  • Скриншоты, GIF-файлы или макеты, если плагин включает в себя функции пользовательского интерфейса.
  • Объяснение, почему это должен быть плагин от самой компании, а не от стороннего разработчика.

Команда Blockly рассматривает поступающие предложения и либо закрывает проблему, либо соглашается с тем, что это был бы хороший плагин от самой компании.

Обсуждение

Далее плагин переходит в фазу обсуждения . Эта фаза включает в себя:

Обсуждение обычно происходит в разделе "Проблемы" на GitHub. Чем меньше масштаб плагина, тем быстрее может пройти этап обсуждения. Более крупные плагины могут привлечь внимание сообщества и вызвать множество споров о правильном решении. Если это происходит в вашей проблеме, поздравляем! Вы нашли то, что действительно важно для людей.

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

В ходе обсуждения мы можем решить, что плагин должен быть сторонним плагином и не должен публиковаться в рамках области видимости @blockly . В этом случае мы объясним причину и закроем этот вопрос.

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

Выполнение

Этапы реализации включают в себя:

  • Запуск npx @blockly/create-package для настройки плагина и его каталога из шаблона. Подробнее...
  • Реализация основной логики для плагина.
  • Реализация пользовательского интерфейса, если потребуется.
  • Тестирование плагина с использованием Mocha.
  • Документирование плагина, включая файл README .

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

Реализация может осуществляться несколькими участниками параллельно. Вы можете совместно разрабатывать плагин в своем собственном форке или посредством запросов на слияние (pull requests) в этот репозиторий. Если вы хотите совместно работать над плагином в этом репозитории, попросите команду Blockly создать для вас ветку с новой функцией.

Плагины следует добавлять в файл gh-pages/_index.html в main ветке проекта blockly-samples. Это позволит им отображаться на нашем сайте плагинов . Плагины от первого лица должны указывать на свою тестовую страницу. Плагины от третьих лиц также можно добавить на эту страницу, и они могут указывать на ссылку по выбору владельца, например, на размещенную демо-версию или страницу npm.

Издательский

Наконец, публикация . Команда Blockly использует Lerna для управления версиями и публикацией всех плагинов.

Каждый четверг публикуются все плагины, которые изменились с момента их последнего релиза. Если вам необходимо опубликовать изменение раньше, пожалуйста, укажите это в своем запросе на слияние (pull request).

Раздел «Плагины» также обновляется по мере публикации новых плагинов.

Plugins that are not ready for publishing should be marked private in their package.json . This may happen if a plugin relies on a not-yet-published change in core Blockly . Core Blockly is published in the last week of each quarter (once every three months).