Перейти к содержимому
M
Все статьи
Разработка 8 мин чтения

Публикация плагина в каталоге moodle.org: требования, проверка и типичные отказы

Как опубликовать плагин Moodle в каталоге moodle.org: требования к коду и архиву, пошаговый процесс и таблица причин отказа.

Как опубликовать плагин Moodle в каталоге moodle.org: требования к коду и архиву, пошаговый процесс и таблица причин отказа.

Каталог плагинов на moodle.org — это не просто хранилище архивов, а витрина с проверкой: плагин попадает в общий список только после рассмотрения командой каталога. Я выкладывала в каталог плагин электронной зачётной книжки и знаю, на каких местах обычно спотыкаются. Ниже — путь от готового кода до публикации и причины, по которым плагин возвращают на доработку.

Зачем публиковать плагин

Причин три. Первая: плагин из каталога ставится и обновляется прямо из админки Moodle, и заказчику не нужно возиться с архивами. Вторая: вокруг опубликованного плагина появляются отчёты об ошибках и предложения, которые улучшают код. Третья: публичная страница — это проверяемая демонстрация вашей работы. Минусы тоже есть: вы берёте на себя поддержку и публикуете код под открытой лицензией. Если плагин содержит логику, специфичную для одного заказчика, или заказчик не готов раскрывать код, публиковать его не нужно: можно спокойно ставить плагин из архива, как описано в разделе про разработку плагинов.

Что нужно до начала

ТребованиеЧто это значит на практике
Совместимая лицензияплагин для Moodle распространяется под GPL версии 3 или новее; заголовки во всех PHP-файлах содержат лицензию
Корректный version.phpзаданы component, version, requires, maturity, release; поддерживаемые версии указываются полем supported
Языковой файлесть lang/en/ с строкой pluginname; английский обязателен, русский добавляется отдельно
Публичный репозиторийссылка на код (обычно GitHub) и ссылка на трекер ошибок
Описание и документациячто делает плагин, как ставить и настраивать; хотя бы README или страница в документации
Privacy APIпровайдер, который описывает, какие персональные данные хранит плагин, или явное заявление, что не хранит
Чистая структура архивавнутри ZIP корневая папка называется именем каталога плагина (например, gradebook), без служебных файлов репозитория

Название компонента (local_gradebook) после регистрации менять нельзя, поэтому имя выбирают заранее. Требования каталога и правила описаны на странице публикации плагинов в документации разработчика; смотрите их свежую версию перед отправкой.

Пошагово: от кода до публикации

  1. Проверить код. Прогнать плагин через phpcs и moodle-plugin-ci (см. стандарты кода и Code Checker), запустить тесты.
  2. Проверить установку с нуля. Поставить архив на чистую установку Moodle подходящей версии и убедиться, что установка, обновление и удаление проходят без ошибок и предупреждений при включённом режиме разработчика.
  3. Собрать архив. В ZIP — только каталог плагина без .git, служебных файлов редактора, макетовских артефактов macOS (__MACOSX, ._*), зависимостей для разработки.
  4. Зарегистрироваться на moodle.org. Нужна учётная запись; публикация идёт от имени её владельца или организации.
  5. Зарегистрировать плагин. В разделе каталога выбирается регистрация нового плагина: название, краткое и подробное описание, адрес репозитория, трекер, документация.
  6. Загрузить первую версию. Каталог распаковывает архив, читает version.php и сам проверяет структуру. Если проверка находит ошибку, она показана сразу, и версию можно загрузить заново.
  7. Дождаться рассмотрения. Сначала плагин считается ожидающим одобрения. Сроки зависят от загрузки команды каталога, поэтому закладывайте время с запасом и не привязывайте к ним релиз у заказчика.
  8. Поддерживать. Новые версии загружаются тем же способом; для каждой указывается, с какими версиями Moodle она совместима.

Типичные причины отказа и возвратов

ПричинаКак проявляетсяЧто делать
Неверная структура архивакорень называется local_gradebook вместо gradebook, или внутри лишняя вложенная папкапересобрать архив: имя корневой папки равно имени каталога плагина
В архиве лишние файлыслужебные каталоги репозитория, зависимости, резервные копииисключить при сборке
Нет или неверная лицензияв файлах нет заголовка GPL либо лицензия несовместимапривести заголовки к стандарту
Нет Privacy APIплагин хранит данные пользователей и не заявляет об этомреализовать провайдер (см. Privacy API в плагине)
Ошибки и предупреждения при установкеnotice и deprecated в режиме разработчикаисправить, особенно в install.php и upgrade.php
Нет описания или документациииз карточки непонятно, что делает плагиндописать описание и инструкцию для администратора
Прямые обращения к ядру в обход APIправка таблиц ядра, переопределение чужих классовпереписать на публичные API и события
Секреты и адреса заказчика в кодепароли, внутренние URL, имена в тестовых данныхубрать, вынести в настройки

Что я проверяю в последнюю очередь

Перед загрузкой я иду по короткому списку, потому что именно эти мелочи возвращают плагин:

  • в version.php число version новое, а requires соответствует самой старой версии Moodle, на которой плагин реально проверен;
  • значение maturity честное: для первого выпуска это альфа или бета, а не «стабильная»;
  • все строки интерфейса вынесены в языковые файлы, в коде нет жёстко прописанного русского текста;
  • права определены в db/access.php и проверяются в коде;
  • в upgrade.php нет вызовов, которые портят данные при повторном запуске;
  • после удаления плагина через админку не остаётся таблиц и настроек.

Версии и поддержка после публикации

После одобрения работа не заканчивается. Для каждой новой ветки Moodle нужно проверять плагин и выпускать совместимую версию, иначе в каталоге он будет значиться как неподдерживаемый для новых релизов. Удобная схема — одна основная ветка кода и метка совместимости, о чём подробнее в статье про совместимость плагина с Moodle 4.1–5.x. Обращения пользователей приходят через трекер: отвечать на них придётся, и лучше сразу понимать, сколько времени вы готовы тратить.

Как оформить страницу плагина

Карточка в каталоге — первое, что видит администратор, выбирающий плагин. Короткое описание должно отвечать на вопрос «для чего это», а не перечислять технологии. Подробное описание я строю по плану: задача, которую решает плагин; для кого он (преподаватель, администратор, слушатель); что нужно для установки; как настроить после установки; известные ограничения. Скриншоты стоит добавить обязательно: плагин без картинок воспринимается как заброшенный. Ограничения лучше называть прямо — «не работает с форматом курса X», «требует включённого Y» — это избавляет от лишних сообщений в трекере.

Отдельно продумайте версионность. Номер в release должен быть понятен человеку (например, 1.2.0), а version — датой с порядковым номером, как принято в Moodle. Каждая выкладка в каталог — это новая запись в истории версий, и по ней пользователи судят, живёт ли проект.

Если плагин вернули на доработку

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

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

Когда каталог не нужен

Публичный каталог подходит не каждому плагину. Если плагин написан под единственного заказчика и содержит его процессы — регламенты, формы документов, особые правила расчётов, — публиковать его бессмысленно, и поддержка чужих запросов будет только мешать. Такой плагин живёт в закрытом репозитории и ставится из архива или по тегу через git. Это не отменяет требований к качеству: стиль, тесты, Privacy API и документация нужны и там, просто проверяет их не рецензент каталога, а вы сами. На практике я разделяю: универсальные плагины, полезные многим учебным заведениям, предлагаю выкладывать, а заказные — оставляю закрытыми по договорённости с заказчиком, прописывая вопрос об исключительных правах в договоре.

Проверка архива перед загрузкой

Архив собирается скриптом, а не вручную, иначе в него обязательно попадёт лишнее. Мой порядок: экспортировать чистое состояние репозитория по тегу (команда git archive не включает служебный каталог git и файлы, перечисленные в .gitattributes как исключаемые), положить результат в папку с именем каталога плагина и упаковать в ZIP.

git archive --format=zip --prefix=gradebook/ -o gradebook.zip v4.16.1
unzip -l gradebook.zip | head -30

Имя каталога в --prefix — это каталог плагина (для local_gradebook — gradebook), тег в примере условный. Вторая команда показывает содержимое: убедитесь, что корень правильный, нет скрытых файлов, дампов базы, файлов с паролями и каталогов зависимостей разработки. Файлы, которые не должны попадать в архив (тесты не обязательны, но документация для разработчика, конфигурации CI, .github), перечисляют в .gitattributes с атрибутом export-ignore. Каталог tests в архиве оставляют: он нужен тем, кто запускает проверки.

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

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.