Публикация в GPM¶

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

Часть 1: Публикация плагина¶

Требования к плагину¶

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

• yourplugin.php — PHP-файл плагина, имя которого должно совпадать с именем папки
• yourplugin.yaml — файл конфигурации плагина, содержащий параметры и информацию о наследовании потоков
• blueprints.yaml — файл определения плагина и файл определения формы
• CHANGELOG.md — файл изменений в правильном формате Grav для единообразного отображения
• README.md — обязательный файл для описания и предварительного просмотра плагина
• LICENSE — файл лицензии, вероятно MIT, если совместим с ядром Grav
• languages.yaml (необязательно) — файл определения языка

В отличие от тем, плагинам не нужны изображения screenshot.jpg или thumbnail.jpg — плагин визуально представлен иконкой Font Awesome icon:, объявленной в его blueprints.yaml, как на getgrav.org, так и в списке плагинов админки.

Файл blueprints.yaml¶

Файл blueprints.yaml в корне плагина — то, что читают GPM и админка, чтобы представить ваш плагин. Реальный пример из плагина Breadcrumbs:

name: Breadcrumbs
type: plugin
slug: breadcrumbs
version: 1.6.3
description: The **Breadcrumbs** plugin provides a simple method to display the depth of your content/navigation structure.
icon: caret-square-o-right
author:
  name: Team Grav
  email: devs@getgrav.org
  url: https://getgrav.org
homepage: https://github.com/getgrav/grav-plugin-breadcrumbs
demo: https://demo.getgrav.org/blog-skeleton
keywords: breadcrumbs, plugin, navigation, depth
bugs: https://github.com/getgrav/grav-plugin-breadcrumbs/issues
license: MIT
compatibility:
  grav: ['1.7', '2.0']

dependencies:
  - { name: grav, version: '>=1.7.0' }

Поля name, slug, type, version, description, author и license обязательны для листинга в GPM. Полный справочник полей, включая раздел form:, определяющий параметры конфигурации плагина в админке, см. в схемах.

Процесс выпуска¶

Когда плагин готов к добавлению в репозиторий, пройдите этот контрольный список:

1. Открытый исходный код с файлом LICENSE, предоставляющим лицензию, совместимую с MIT. Пример здесь
2. Содержит файл README.md с описанием функциональности и инструкциями по установке и настройке. Пример здесь
3. Содержит файл blueprints.yaml со всеми обязательными полями. Пример здесь
4. Предоставляет CHANGELOG.md в правильном формате. Пример здесь
5. Указывает соответствующую атрибуцию, если вы используете другие библиотеки, скрипты или код.
6. Создайте релиз готового плагина. Система репозитория Grav требует релиз и не найдёт ваш плагин, если нет релиза, содержащего всё перечисленное.
7. Добавьте issue в трекер Grav с подробностями о плагине, и мы быстро проверим его работоспособность, после чего добавим.

Формат списка изменений¶

Сайт GetGrav.org использует собственный формат ChangeLog, написанный в стандартном Markdown, но который можно обработать простым CSS и отобразить в привлекательном виде. Чтобы ваши ChangeLog корректно разбирались и форматировались, используйте этот синтаксис:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# X.Y.Z
## 2015-01-01

1. [](#new)
    * New features added
    * Another new feature
2. [](#improved)
    * Improvement made
    * Another improvement
3. [](#bugfix)
     * Bugfix implemented
     * Another bugfix

...repeat...

Каждый раздел #new, #improved, #bugfix необязателен; включайте только нужные разделы.

Демонстрационный контент¶

Вы можете предоставить демонстрационный контент как часть пакета плагина. Это значит, что всё, что находится в папке _demo/, будет скопировано в папку user/ в процессе установки. Так можно предоставить страницы, конфигурацию или что угодно ещё, что находится в папке user/. Пользователю будет предложено сделать это, и это совершенно необязательно.

Обратите внимание: демонстрационный контент не копируется при установке плагина через админку.

Часть 2: Обновления и сопровождение¶

Выпуск обновлений¶

После того как плагин добавлен в репозиторий, не нужно открывать issue для новых версий. Измените version: в blueprints.yaml, добавьте соответствующую запись в CHANGELOG.md и опубликуйте новый релиз GitHub — GPM подхватит его автоматически, а пользователи увидят обновление в админке и через bin/gpm update.

Протокол заброшенных ресурсов¶

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

1. Отправьте хорошо оформленный и протестированный pull request в исходный репозиторий.

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

3. Отправьте новый issue в репозиторий Grav на GitHub со следующими сведениями:

4. Заголовок: [change-resource] Take over plugin/theme

5. Укажите название плагина и ссылку на исходный репозиторий.

6. Дайте ссылку на ваш pull request, оставшийся без ответа, или на обсуждение, в котором сопровождающий отказался от ресурса.

7. Сопровождающие Grav рассмотрят случай и сообщат, одобрено ли принятие. Если одобрено, переходите к следующему шагу.

8. Подготовьте форк репозитория с новым релизом.

9. Добавьте в README примечание, что этот репозиторий теперь основной, и ссылку на старый репозиторий.

10. Ответьте в issue, сообщив сопровождающим новый URL плагина.

11. Сопровождающие обновят GPM, и новые и обновлённые установки будут происходить из вашего форка.