Как подготовить плагин к публикации

Пользователи Трекера могут найти и подключить плагины в каталоге: Расширить возможности Трекера с помощью плагинов.

Перед публикацией прочитайте Соглашение с разработчиком плагинов для каталога плагинов сервисов Яндекс 360.

Чтобы добавить разработанный вами плагин в каталог:

1. Подготовьте для плагина описание и изображения.

2. Подготовьте справку — документацию для пользователей.

3. Отправьте плагин на публикацию.

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

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

Оформление карточки

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

• public/logo.svg — логотип плагина, должен иметь квадратную форму;
• marketplace/header-image.jpg — изображение для карточки плагина, должно иметь пропорции 2,41:1;
• marketplace/index.md — описание для карточки плагина.

Название

• Используйте от 3 до 32 символов.
• Пишите название на русском языке. Исключение — официальные названия брендов и продуктов, например Figma или Miro.
• Не добавляйте в название слова «плагин», «виджет», «приложение» и похожие обозначения.
• Не называйте плагин только по имени сервиса, с которым он интегрируется.
• Не используйте название, которое совпадает с названием существующего плагина или приложения более чем на 90%.
• Не ставьте точку в конце.

Для интеграции с внешним сервисом составьте название по схеме «функция + сервис». Например: Отправка сообщений в Telegram.

Краткое описание

Краткое описание отображается в карточке плагина в каталоге. Оно должно дополнять название и объяснять основную функцию плагина.

• Напишите одно-два предложения общей длиной до 75 символов.
• Не ставьте точку в конце.

Например:

• название — Скрытые заметки;
• краткое описание — Приватное пространство для заметок внутри задачи с гибкими правами доступа.

Полное описание

Полное описание должно содержать не более 4000 символов. В него можно добавлять маркированные и нумерованные списки. Не добавляйте внешние ссылки и рекламу.

Рекомендуемая структура полного описания:

1. Какие задачи решает плагин. Перечислите его основные возможности.
2. Для кого предназначен плагин. Укажите роли или должности пользователей, которым он будет полезен.
3. Как использовать плагин. Добавьте краткую инструкцию или сценарий использования.

Стиль и тон текста

• Пишите нейтрально и информативно. Не используйте рекламные обещания, превосходную степень и неподтвержденные оценки, например «лучший» или «№ 1».
• Используйте буквы, цифры, одиночные пробелы и необходимые знаки препинания. Не добавляйте эмодзи, восклицательные знаки и специальные символы, например @, #, $, %, ^, &, *.
• Не используйте прописные буквы для выделения текста. Исключение — аббревиатуры длиной не более четырех букв, например API или CRM.
• Пишите нарицательные существительные со строчной буквы.
• Не сокращайте слова.
• Названия брендов и продуктов пишите так же, как на их официальных сайтах и в документации.
• Различайте дефис и тире. Например, правильно: Харон — экспорт данных; неправильно: Харон - экспорт данных.
• Используйте букву ё, если без нее слово можно прочитать неправильно, а также в редких словах и именах собственных.

Категория плагина

Для удобства поиска плагины в каталоге группируются по категориям. При создании или публикации плагина нужно указать категории. Категории задаются в манифесте в поле categories.

Полный список доступных категорий:

Справка плагина

Справка — это документация вашего плагина для пользователей. Она отображается в каталоге плагинов и в точке интеграции в интерфейсе Трекера.

Существует два способа подключить справку: разместить её на внешнем домене или включить прямо в дистрибутив плагина.

Внешняя справка

Если документация уже размещена на вашем домене, укажите ссылку на неё в поле docsUrl файла manifest.json:

{
    "docsUrl": "https://example.com/docs/plugin.html",
    "slots": {
        "tracker": {
            "issue.action": [
                {
                    "entrypoint": "index.html",
                    "contextLevel": "basic",
                    "title": {
                        "ru": "Мой плагин",
                        "en": "My Plugin"
                    }
                }
            ]
        }
    }
}

Трекер отобразит ссылку на справку в каталоге плагинов и в точке интеграции вашего плагина.

Внутренняя справка

Если вы хотите включить документацию прямо в дистрибутив плагина, создайте папку docs/ в корне проекта и разместите в ней файлы index.md и toc.yaml. Файл toc.yaml описывает структуру документа:

title: My Docs
href: index.md
items:
    - name: Introduction
      href: index.md
    - name: Getting Started
      href: getting-started.md
    - name: Reference
      href: reference.md

Структура файлов

Минимальная структура для одностраничной справки:

docs/
├── toc.yaml
└── index.md

Превью

Если вы хотите посмотреть, как документация будет выглядеть — запустите команду build-docs и откройте docs-build/index.html в браузере.

Публикация справки

При публикации плагина справка автоматически собирается с помощью Diplodoc. После успешной проверки в манифест плагина будет проставлена ссылка /docs/index.html.

Справка не встраивается в интерфейс Трекера — пользователь переходит по ссылке, как и в случае с внешней справкой.

Публикация плагина

Чтобы отправить плагин на публикацию:

1. Получите токен для CLI:

   weavix login
   

2. Запустите публикацию:

   weavix submit
   

   Команда сама выполнит регистрацию плагина при необходимости, загрузку дистрибутива и отправку версии на модерацию.

3. После отправки на модерацию проверяйте статус публикации:

   weavix list
   

   Чтобы посмотреть замечания модератора к версии плагина, выполните команду:

   weavix info
   

   Команда покажет замечания под соответствующей версией с именем автора и датой. В выводе weavix list замечания не отображаются.

Публикация в публичном каталоге

Публичность — свойство плагина, а не отдельной версии. Способ публикации зависит от текущего состояния плагина.

weavix upgrade

Перед публикацией плагина

Команды submit --public и make-public проверяют, что в карточке плагина указаны:

• name, description, support, categories и slug в manifest.json;
• marketplace/index.md;
• marketplace/header-image.jpg.

Поля манифеста описаны в разделе Описание плагина в manifest.json.

Обе команды также проверяют архив на секреты. Если CLI найдет возможные секреты, исправьте их или отметьте ложные срабатывания в интерактивном списке. CLI выводит отпечаток (fingerprint) для каждого срабатывания.

При любом запуске make-public нужно подтвердить необратимое изменение видимости. Чтобы пропустить подтверждение, добавьте флаг --yes. При запуске без терминала этот флаг обязателен.

При запуске без терминала явно подтвердите отпечатки ложных срабатываний:

weavix make-public <plugin-id> --yes --ack <fingerprint...>

Если при неинтерактивном запуске submit --public найдены возможные секреты, плагин уже зарегистрирован. Используйте идентификатор плагина и отпечатки из вывода CLI в команде выше, а затем отправьте версию командой weavix submit.

Новый или еще не опубликованный плагин

Выполните команду:

weavix submit --public

CLI зарегистрирует плагин, переключит его видимость на PUBLIC и отправит версию на модерацию Яндекса. После одобрения версия появится в публичном каталоге и станет доступна пользователям всех организаций.

Если плагин уже публичный, отправляйте новые версии командой weavix submit без флага --public. Если плагин уже опубликован в каталоге организации, CLI завершит команду с ошибкой и сообщит, что нужно выполнить make-public.

Команду make-public можно выполнить и для зарегистрированного, но еще не опубликованного плагина: она сразу переключит видимость на PUBLIC, но не отправит версию. После этого отправьте версию командой weavix submit.

Плагин, опубликованный в организации

Чтобы опубликовать в публичном каталоге последнюю версию, одобренную организацией, выполните команду:

weavix make-public

Если нужно опубликовать другой плагин, укажите его идентификатор:

weavix make-public <plugin-id>

Если карточка плагина заполнена не полностью, заполните данные из списка CLI. Затем отправьте новую версию командой weavix submit и дождитесь одобрения организации. После этого снова выполните weavix make-public.

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

weavix info

Команда покажет идентификатор и статус заявки, идентификатор версии, даты подачи и решения, а также комментарий модератора.

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

weavix withdraw --publication

Для другого плагина передайте его идентификатор: weavix withdraw --publication <plugin-id>.

Добавление в каталог

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

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

Чтобы плагин, созданный для вашей организации, стал доступен всем пользователям Трекер, опубликуйте его в публичном каталоге. После одобрения Яндексом плагин появится в публичном каталоге.