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

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

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

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
   

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

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

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

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