mirror of
https://github.com/Bayselonarrend/OpenIntegrations.git
synced 2024-11-28 09:08:38 +02:00
104 lines
12 KiB
Markdown
104 lines
12 KiB
Markdown
# Добро подаловать в правила участия проекта Открытого пакета интеграций!
|
|
|
|
В этом документе вы можете найти информацию о том, как правильно реализовать и оформить свой вклад в данный проект. Мы всегда рады новым участникам, так что если у вас есть идея, пожелание или, тем более, реализация какой-нибудь классной штуки, которая поможет проекту стать лучше, то обязательно поделитесь ей с нами.
|
|
|
|
Однако, всем нам будет гораздо проще взаимодействовать друг с другом, если мы заранее оговорим правила и формы данного взаимодействия. И если в случае с Issues неправильная форма может привести разве что к лишним уточняющим вопросам, то незнание структуры и соглашений в работе с кодом с большой долей вероятности приведет к переделкам и отклоненным PR.
|
|
|
|
Так что, если вы - потенциальный участник, то не стоит относится к этому документу легкомысленно. Несколько минут, потраченные на его прочтение, помогут всем нам сэкономить самый важный ресурс человечества - время.
|
|
|
|
|
|
## Как принять участие в проекте?
|
|
|
|
Если вы решили стать постоянным участником или даже просто разово помочь проекту ОПИ, то сделать это можно двумя способами:
|
|
|
|
- Написать Issue о найденом баге или возникшем пожелании
|
|
- Реализовать новый или улучшить существующий функционал проекта
|
|
|
|
Об этих двух вариантах и пойдет речь далее
|
|
|
|
## Создание Issue
|
|
|
|
Самый простой способ поучастовать в развитии проекта - написать в [Issues](https://github.com/Bayselonarrend/OpenIntegrations/issues) данного репозитория.
|
|
|
|
Писать туда можно о чем угодно, но в первую очередь приветствуются сообщения об ошибках, непредвиденном поведении программы и неоптимальностях в её работе. Если вы заметили нечто подобное в процессе работы с ОПИ или даже если у вас есть просто подозрения на этот счет - обязательно напишите. Также приветствуются и предложения о новом или переработке старого функционала: не все подобные предложения принимаются, но точно все обусуждаются
|
|
|
|
В зависимости от вида информации, которой вы хотите поделиться, в Issues есть разные шаблоны сообщений
|
|
|
|
|
|
|
|
Следование данным шаблонам поможет не забыть указать все нюансы, которые могут быть важны при решении того или иного вопроса, а также, как уже было сказано ранее, избежать лишних распросов с нашей стороны. Ничего особенно плохого в вопросах нет, но несовпадение во времени активности участников диалога по созданному Issue может привести к затягиванию решения проблемы и просрочке дедлайна следующего релиза
|
|
|
|
## Запросы на слияние
|
|
|
|
Начнем с простого - запросы на слияние. В создании PR самих по себе нет никаких особо строгих правил: форк -> изменения -> запрос. Все PR рассматриваются и, если отклоняются, то как правило только с комментарием о недоработках.
|
|
|
|
ОПИ - проект довольно строгий, как буде рассмотрено далее. Так что будет очень хорошо, если запросу на слияние будет предшествовать Issue, где мы вместе обсудим необходимость и способ реализации того или иного нововведения. Теперь перейдем к сложному - к коду
|
|
|
|
|
|
## Работа с кодом
|
|
|
|
Открытый пакет интеграций - проект с огромным количеством нюансов и соглашений. Вносить свой вклад новичку в него непросто, но этому есть свои причны, о которых сейчас и пойдет речь
|
|
|
|
Во-первых, ОПИ распространяется в 3-х версиях:
|
|
- 1С (OPI)
|
|
- OneScript (OInt)
|
|
- CLI (OInt CLI)
|
|
|
|
При этом, напрямую разрабатывается всего одна версия - версия для 1С, и только в эту версию вносятся изменения. В остальные две версии изменения "руками" никогда не вносятся - они создаются автоматически в паплайне на Github Actions. Такой подход позволяет всегда иметь все 3 версии в симметричном и актуальном состоянии, но и рождает некоторые правила и соглашения, без которых ничего работать не будет
|
|
|
|
> Тут стоит сразу оговорится: ОПИ, как вы уже наверняка знаете, это инструменты для работы с различными API. Так вот создание новых API, т.е. полностью новых модулей для работы с новыми сервисами, в рамках участия в проекте, недопустимо. Не создавайте их - они не будут приняты. <br/><br/>
|
|
> Далее из текста будет понятно почему, но если вкратце: автоматизированное тестирование методов для работы с публичными API онлайн-сервисов требует данных и знаний об их работе, чего у меня, как мейнтейнера, не будет, если я не буду хотя бы в теме основы реализованного модуля. Если у вас есть идея создания модуля для нового API - напишите Issues, а там мы вместе подумаем и заложим основу, чтобы я потом мог нормально гонять тесты и понимал, чем этот сервис и этот модуль дышат <br/><br/>
|
|
> Проще всего принимаются PR с багфиксами существующих методов - для них большинство описываемых далее соглашений не играют роли, чуть сложнее - новые методы. К последним применимо все описанное далее
|
|
|
|
Автоматизация выпуска версий основана на двух вещах
|
|
- Документирующие комментарии
|
|
- Тесты
|
|
|
|
Документирующие коментарии - важнейшая вещь. На них основаны
|
|
- Формирование состава команд CLI версии
|
|
- Справка CLI версии
|
|
- Автоматическое создание документации для [openintegrations.dev](https://openintegrations.dev)
|
|
|
|
Рассмотрим типичный докуменитрующий комментарий к одному из методов:
|
|
|
|
```bsl
|
|
|
|
// Отправить текстовое сообщение
|
|
// Отправляет текстовое сообщение в чат или канал
|
|
//
|
|
// Параметры:
|
|
// Токен - Строка - Токен бота - token
|
|
// IDЧата - Строка,Число - ID целевого чата или IDЧата*IDТемы - chat
|
|
// Текст - Строка - Текст сообщения - text
|
|
// Клавиатура - Строка - См. СформироватьКлавиатуруПоМассивуКнопок - keyboard - JSON клавиатуры или путь к .json
|
|
// Разметка - Строка - Вид обработки текста (HTML, Markdown, MarkdownV2) - parsemode
|
|
//
|
|
// Возвращаемое значение:
|
|
// Соответствие Из КлючИЗначение - сериализованный JSON ответа от Telegram
|
|
Функция ОтправитьТекстовоеСообщение(Знач Токен
|
|
, Знач IDЧата
|
|
, Знач Текст
|
|
, Знач Клавиатура = ""
|
|
, Знач Разметка = "Markdown") Экспорт
|
|
|
|
...
|
|
|
|
```
|
|
|
|
- В первой строке комментария определяется краткое описание функции. Оно используется как заголовок страницы онлайн-документации, в транслитированном виде как её URL и как описание команды в CLI версии
|
|
- Во второй строке определяется развернутое описание для онлайн-документации
|
|
- Далее идут описания параметров функции, каждое из которых состоит из 4 частей: имени параметра, типов данных, краткого описания и имени опции для CLI версии
|
|
- Завершается комментарий типом и описание возвращаемого значения
|
|
|
|
В целом - это стандартный формат комментария, который формируется в EDT через ПКМ -> Источник -> Генерировать комментарии к методу, за тем лишь исключением, что верхняя часть комментария всегда из двух строк, а к описанию параметров добавляется четвертая секция с именем CLI опции
|
|
|
|
|
|
|
|
В документирующих комментариях не допускается:
|
|
- Описание параметров длиннее 120 символов
|
|
- Описание параметра с переносом на новую строку - один параметр = одна строка
|
|
- Использование спецсимволов в именах CLI опций
|
|
- Использование слишком длинных имено CLI опции (в идеале - 3-7 символов)
|
|
|
|
** Продолжение в процессе работы **
|