From 71564fcedcf4bb3e459dd7de62af922def2741bd Mon Sep 17 00:00:00 2001 From: CuberHuber Date: Thu, 21 Nov 2024 19:28:53 +0300 Subject: [PATCH] 1. Added quick starting guide. 2. Added temp information about badges Resolves: #36 --- readme.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index 65ae178..9842b36 100644 --- a/readme.md +++ b/readme.md @@ -4,6 +4,11 @@ [![Release plugin](https://github.com/S3-Platform-Inc/s3-platform-plugin-template/actions/workflows/build-release.yml/badge.svg)](https://github.com/S3-Platform-Inc/s3-platform-plugin-template/actions/workflows/build-release.yml) [![Sync plugin to S3](https://github.com/S3-Platform-Inc/s3-platform-plugin-template/actions/workflows/sync-release.yml/badge.svg)](https://github.com/S3-Platform-Inc/s3-platform-plugin-template/actions/workflows/sync-release.yml) +> [!WARNING] +> В документации к плагину используются GitHub Badges - это динамические шильдики, которые в этом кейсе показывают статус работы Github Actions. +> Необходимо обновить ссылки в шильдиках. Заменить `s3-platform-plugin-template` на `название репозитория плагина`. +> _Удалить это напоминание из readme.md + > [!NOTE] > Нажми на Use this template кнопку и клонируй его в IDE. @@ -15,6 +20,7 @@ S3 Platform Plugin Template - это репозиторий предоставл [//]: # (Если вы все еще не совсем понимаете, о чем идет речь, прочитайте наше введение: Что такое S3 Platform?) # Содержание +- [Быстрый старт](#быстрый-старт) - [Обновление зависимостей](#обновления-зависимостей) - [Требования](#требования-к-разработке-плагина) - [Структура](#обязательная-структура) @@ -23,9 +29,39 @@ S3 Platform Plugin Template - это репозиторий предоставл - [Как запустить тесты](#запуск-тестов) - [Правила написания парсера](#правила-написания-парсеров) +## Быстрый старт + +1. На GitHub: + 1. В GitHub выбрать `Use this template` для создания плагина. + 2. Назвать новый плагин в соответствии с [требованиями](#название-репозитория). + 3. **ПРОПУСТИТЬ ШАГ, ЕСЛИ РЕПОЗИТОРИЙ СОЗДАЕТСЯ В РАМКАХ [ОРГАНИЗАЦИИ](https://github.com/S3-Platform-Inc)**. Добавить секреты в репозиторий (см. [тут](#секреты)). + 4. Открыть новые issue (пример названия: `New plugin: xxx` или `add payload xxx`) + 5. Создать новую ветку в проекте, наследуемую от `main` (пример названия: `feature/{issue id}-new-plugin`). +2. В IDE: + 1. Скачаем новый репозиторий `git clone [repo name]`. + 2. Переключаемся в новую ветку `git checkout feature/{issue id}-new-plugin`. + 3. Прочитать [требования](#требования-к-разработке-плагина). + 4. Обновить Github Badges в начале файла `readme.md` (`s3-platform-plugin-template` на `название репозитория плагина`). + 5. Придумать название плагина в соответствии с [требованиями](#название-плагина). + 6. Обновить [GitHub Actions](#обновление-cicd-). + 7. Обновить [декларацию плагина](#pluginxml). + 8. Обновить документация (`readme.md`): Заголовок, описание, характерные особенности парсера и логика работы, эксклюзивные начальные параметры парсера. + 9. Написать логику плагина (см. [тут](#правила-написания-парсеров)). + 10. Обновить конфигурацию плагина (см. [тут](https://github.com/S3-Platform-Inc/s3p-sdk/blob/main/docs/config.md)). + 11. Обновить тесты и дописать новые при необходимости (см. [тут](#тесты)). + 12. Запустить тесты (см. [тут](#запуск-тестов)). + 13. Если все тесты пройдены, сохраняем изменениями (`git commit ...` и `git pull`). +3. На GitHub: + 1. Создать pull request для ветки `feature/{issue id}-new-plugin`. + 2. Дождаться завершения `Checks` для PR. + 3. **ШАГ ОБЯЗАТЕЛЕН В РАМКАХ [ОРГАНИЗАЦИИ](https://github.com/S3-Platform-Inc)**. Указать в PR админа: `Assignees` -> `CuberHuber` + 4. **ПРОПУСТИТЬ ШАГ, ЕСЛИ РЕПОЗИТОРИЙ СОЗДАЕТСЯ В РАМКАХ [ОРГАНИЗАЦИИ](https://github.com/S3-Platform-Inc)**. Слить изменения и закрыть PR. + +------------ + ## Обновления зависимостей При работе над плагином важно поддерживать его версию в актуальном состоянии. Шаблон плагинов и версия SDK часто обновляются, из-за начальной стадии продукта. -Чтобы сихронизироваться с шаблоном можно выполнить следующие действия. +Чтобы синхронизироваться с шаблоном можно выполнить следующие действия. > [!NOTE] > Рекомендуется выполнять синхронизацию мануально. Таким образом вы сможете исправить потенциальные конфликты при слиянии. @@ -47,6 +83,32 @@ git merge template/main --allow-unrelated-histories ## Требования к разработке плагина +### Правила наименований + +#### Название репозитория +Общий шаблон названия репозитория +``` +s3p-plugin-[type]-[uniq_name] +``` +Шаблон названия репозитория парсера +``` +s3p-plugin-parser-[uniq_name] +``` +Пример названия репозитория парсера +``` +s3p-plugin-parser-emvco +``` + +#### Название плагина +Шаблон названия плагина схож с названием репозитория. +``` +s3p_plugin_[type]_[uniq_name] +``` +Пример названия репозитория парсера +``` +s3p_plugin_parser_emvco +``` + ### Обязательная структура Репозиторий плагина состоит из основных компонентов: @@ -74,7 +136,7 @@ my-plugin/ # Репозиторий [ version ] ``` -- уникальное имя плагина [`uniq plugin name`]. Используется как имя каталога с файлами плагина и в тестах. +- уникальное имя плагина [`uniq plugin name`] см. [тут](#название-плагина). Используется как имя каталога с файлами плагина и в тестах. - версия плагина [`version`]. Имеет формат `[N > 0].[N >= 0]`. Последняя стабильная версия по умолчанию - `3.0`. #### src @@ -103,7 +165,7 @@ my-plugin/ # Репозиторий #### Секреты **CI/СD:** -- `RELEASE_TOKEN`: создается в GitHub для работы с релизами репозиториев (см. [здесь](https://github.com/settings/personal-access-tokens)). +- `PLUGIN_RELEASE_TOKEN`: создается в GitHub для работы с релизами репозиториев (см. [здесь](https://github.com/settings/personal-access-tokens)). S3 Platform использует Amazon S3 в качестве [объектного хранилища](https://ru.wikipedia.org/wiki/Amazon_S3). Следующие секреты требуются для подключения к нему (_Все 5 значений можно получить в панели администратора хранилища_):