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

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

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

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

Первая сторона против третьей стороны

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

Плагины первой стороны поддерживаются командой Blockly и опубликованы под @blockly scope на npm. Они разработаны для использования в широком спектре приложений Blockly, стабильны и просты в использовании. Они хранятся в blockly-samples . Поле для установки скорости двигателя может использоваться во многих робототехнических проектах и ​​является хорошим кандидатом для плагина первой стороны.

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

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

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

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

Процесс

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

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

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

Узнайте, как написать запрос на функцию

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

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

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

Обсуждение

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

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

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

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

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

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

Выполнение

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

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

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

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

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

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

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

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

Сайт плагинов также обновляется каждый раз при публикации плагинов.

Плагины, которые не готовы к публикации, должны быть помечены как private в их package.json . Это может произойти, если плагин опирается на еще не опубликованное изменение в ядре Blockly . Ядро Blockly публикуется в последнюю неделю каждого квартала (раз в три месяца).