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

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

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

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

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

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

Плагины собственной разработки поддерживаются командой Blockly и опубликованы в разделе @blockly на 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. Чем меньше тема плагина, тем быстрее может пройти этап обсуждения. Более крупные плагины могут привлечь внимание сообщества и сформировать чёткие мнения о правильном решении. Если это происходит и с вашей задачей, поздравляем! Вы нашли то, что интересно людям.

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

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

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

Выполнение

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

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

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

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

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

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

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

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

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

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