Предыстория (ее можно пропустить)
Контроль качества (опционально)
Ssl-ci. Работа с файлами. Команды.
Ssl-ci. Автодеплой (опционально).
Краткое содержание статьи
В данной статье решил рассказать, как у нас в команде устроена работа с дополнительными отчетами и обработками (далее просто внешние файлы).
Расскажу про расширение для связи гита и вашей конфигурации на основе БСП.
Расскажу, как мы версионируем файлы, как мы их разрабатываем, как тестируем и как автоматически обновляем везде, где это может понадобиться.
Надеюсь, наш опыт будет полезен и для вас.
Краткое содержание в виде таблички
| Глава | Польза | Применимость | Инструменты | |
|---|---|---|---|---|
| Версионирование |
У вас появится удобное версионирование дополнительных отчетов и обработок. Всегда можно будет понять по какой задаче что менялось и насколько у вас актуальные версии в базе. |
Обязательно. Без версионирования расширение не имеет смысла и по одной кнопке вы ничего не сможете обновить. В принципе можно не раскладывать файлы на исходники, но тогда след.пункты будут неприменимы. |
git + Oscript + |
|
| Разработка |
|
Опционально. т.е. без этого можно жить, но непонятно зачем. |
vs code | |
| Контроль качества |
Не будет нарушения стандартов разработки 1С Все отчеты не будут внезапно падать с синтаксической ошибкой при обновлении релиза |
Опционально. Если вам не важно качество вашей разработки, то можно пропустить. |
SonarQube, vanessa add (дымовые тесты) | |
| Код-ревью |
В дополнение к соблюдению стандартов 1С будут соблюдаться ваши внутренние стандарты разработки Из внешних файлов исчезнет “плохой код” (но это не точно) |
Опционально. Как показывает практика, код внешних отчетов и обработок вообще редко кто системно проверяет. |
vs code, Конфигуратор | |
|
Ssl-ci (Расширение)
|
Интеграция гита и вашей базы. Обновление всех файлов по одной кнопке. История изменения файла прямо в вашей базе. +Много других сервисных возможностей |
Обязательно. Без расширения не было бы и статьи. |
|
|
| Ssl-ci. Автодеплой |
Автоматическое добавление и обновление всех дополнительных отчетов и обработок в любой вашей базе в ходе тестирования контура ci. Вы сможете полноценно использовать сценарное и дымовое тестирование отчетов и обработок. |
Опционально. Можно жить и без ночных сборок проекта и тестов. |
Весь код из статьи и расширение доступно в моем репозитории на ГитХабе Ssl-ci (лайк, шер, репост).
Предыстория (ее можно пропустить)
Практически на каждой моей работе в том или ином виде использовались внешние отчеты и обработки. Это и дополнительные печатные формы, и отчеты, сервисные и не очень сервисные обработки чего-нибудь.
Практически везде, где я работал, внешние файлы делались так:
-
Копируется шаблон обработки (например с инфостарта)
-
Дописывается своя бизнес-логика
-
Сохраняется на свой компьютер. В лучшем случае, на общую шару.
-
Заливается вручную в рабочую базу. В лучшем случае, отдается сначала на тестирование аналитику.
Такой подход обычно приводит к тому, что в папке с внешними файлами образуется бардак вида:
Бардак)
При этом понять кто, когда и главное зачем что-то поменял в таком файле становится невозможно.
Отдельные сложности возникают при параллельной работе над одним файлом двух разработчиков. Скорее всего, в рабочую базу попадут доработки только одного из них.
Поддержание качества кода и тестирование таких файлов в общем-то невозможно.
И на моем текущем проекте был полный набор указанных проблем.
Мы разрабатываем большую высоконагруженную логистическую систему в Почте России.
Под большой и высоконагруженной я понимаю систему на 5 тысяч уникальных пользователей и одновременной работе около 600-900 человек практически 24/7. Как вы понимаете, если условный разработчик Вася накосячит в какой-нибудь критичной печатке или отчете это нам выльется в порядка 300 заявок на хелпдеск.
Поэтому вопрос нормальной организации процесса разработки внешних файлов для нас был довольно-таки критичен.
Предупреждая возможные вопросы - в расширение мы все вынести не могли, потому что при применении расширения нужно все равно 600 пользователям перезайти в базу. И так по несколько раз в день. Каждый день.
Включать все доработки внутрь конфигурации мы тоже не могли, т.к. у нас месячный релизный цикл, и ключевые заказчики не хотели столько ждать новой колонки в какой-нибудь важный отчет.
Итак, вводные я обозначил, теперь расскажу, как мы изменяли процесс.
Версионирование (обязательно)
На первом шаге мы решили включить нормальное версионирование всех файлов. То есть подключить нашу общую папку к гиту.
Мы создали новый репозиторий, выгрузили в него все файлы из рабочей базы и дополнили всеми файлами с машин разработчиков.
Важный момент. Просто хранить файлы в гите конечно хорошо, но хотелось бы на этом шаге получить и структуру кода, которую эти файлы содержат. Тут нам подошел инструмент precommit1c - это набор скриптов, написанных на OneScript. Прекоммит умеет разбирать файлы обработок, отчетов и расширений на исходные файлы.
Для инвентаризации можно запустить команду precommit1c --decompile с аргументами (аргументы доступны в справке) и все ваши файлы разберутся на исходники.
Также на этом шаге мы “очистили” имена внешних файлов от дат и версий, таким образом одному элементу справочника “Дополнительные отчеты и обработки” стал соответствовать один файл в репозитории.
Бонусом этого шага мы получили быстрый поиск по коду по всем отчетам и обработкам. Это особенно полезно при удалении/переименовании метаданных в основной конфигурации.
Разработка (опционально)
Следующим шагом нам нужно было наладить прозрачный процесс доработки внешних файлов.
Поскольку на прошлом шаге у нас уже появился отдельный репозиторий со всеми нашими файлами, то логичным продолжением стало заведение локальных репозиториев для каждого разработчика.
В гите есть некий аналог подписок на события из 1с, называется хук (hook). Если вы создаете новый гит репозиторий (например через git gui), то репозиторий создается сразу с шаблонами таких хуков (samples).
Шаблоны хуков
Как можно понять из названия “precommit 1c” как раз и рассчитан на вызов перед любым коммитом. Он анализирует файлы коммита и, если там есть подходящие по фильтру файлы, раскладывает их на исходники и помещает в тот же коммит. Таким образом разработчик коммитит только файл вида “МояОбработка.epf”, а вся “подкапотная магия” по выгрузке обработки в исходные файлы проходит в хуке прекоммита.
Хук прекоммит, вызываем файл precommit.cmd из корня репозитория
Файл precommit.cmd
Также в гите есть замечательный хук “commit-msg”, который вызывается для проверки сообщения коммита. У нас все изменения на проекте проходят через Jira, так что при внутренней разработке указание номера задачи в Jira у нас обязательно. И как раз благодаря этому хуку мы можем проверить, что разработчик не забыл указать номер задачи, по которой он делает изменения.
Хук проверяет, что мы не забыли указать номер задачи за исключением мерж-коммита. Простая регулярка
Чтобы эти хуки появились в локальном репозитории разработчика, я сделал специальный cmd файл “Настроить проект.cmd”, который любой разработчик запускает перед началом работы в локальном репозитории.
Настройка локального репозитория. Копируем хуки.
Тут мы решаем сразу несколько проблем.
Благодаря модели ветвления гита у нас перестал “теряться” код.
Если два разработчика изменяют один и тот же файл, то при помещении этого файла вторым разработчиком он не сможет случайно затереть работу коллеги.
Сразу мержить в гите на этом шаге показалось сложно, поэтому мы для себя решили в этих случаях поступать так:
-
если при помещении изменений в гит возник конфликт слияния, то разработчик сохраняет себе вне репозитория свою версию файла с конфликтом
-
принимает все изменения из удаленного репозитория (т.е. свои изменения затираются)
-
сравнением/объединением в конфигураторе объединяет два файла в единый новый файл
-
коммитит этот файл в удаленный репозиторий.
Появилась возможность по каждой строке кода “провалиться” в задачу в Jira и понять, почему эта строка тут появилась.
Переход в задачу из коммита
По какой задаче какая строка появилась в файле. Комменты в коде больше не нужны
Контроль качества (опционально)
После того как у нас все внешние файлы лежат и дорабатываются через гит, мы решили наладить контроль качества.
Сначала подключаем анализ сонаром репозитория. Тут все стандартно.
Проект в сонаре
Сам анализ у нас сейчас запускается через Дженкинс.
Периодически смотрим, появились ли новые коммиты
На этом шаге мы решили заодно обновлять файловую шару с нашими отчетами/обработками.
На сервере, где крутится нода дженкинса, мы подключили нашу файловую шару как сетевой диск (диск z). Далее завели там новый локальный репозиторий и средствами дженкинса настроили в едином пайплайне проверку сонаром и обновление этого репозитория.
Пайплайн для дженкинса. На первом шаге обновляем диск z, на втором запускаем анализ сонаром
Теперь, когда у нас появилась единая шара с актуальными отчетами/обработками, мы смогли запустить в наших сборках проекта часть дымовых тестов внешних файлов из vanessa add (если кому-то будет интересно, могу написать, как мы у себя запускали дымовое тестирование), а именно
Все они используют настройку КаталогиВнешнихОтчетов, которая как раз предполагает наличие общей шары.
Код-Ревью (опционально)
На этом же шаге мы ввели практику код-ревью внешних файлов.
Для этого раз в месяц ответственный разработчик берет все накопившиеся изменения по файлам и проводит их ревью.
Для того чтобы понять точку отсчета изменений, мы стали использовать тэги
По тэгам можно отсчитывать контрольные точки репозитория
Всегда можно посмотреть различия между актуальной версией и последним ревью
При этом какие-то изменения было удобно смотреть прямо в гитлабе, какие-то через конфигуратор. Поэтому схема на этом этапе у нас была следующая:
-
Клонируется второй локальный репозиторий, версия этого репозитория переключается на последний проверенный тэг
-
Либо посредством гита, либо через конфигуратор (сравнить/объединить) проводится ревью изменений. Иногда обоими способами.
-
По результатам ревью создаются задачи на разработчиков по исправлению замечаний
-
Ставится новый тэг
Пример служебного репозитория для код-ревью
Такой подход имел ряд недостатков, а именно:
-
изменения проходили ревью слишком поздно и были загружены в рабочую базу;
-
приходилось в задаче указывать скриншоты проблемных кусков кода;
-
после исправления замечаний все доработки нужно было тестировать заново. (Что навело нас на мысль о регрессионном тестировании всех наших внешних файлов).
Но как говорится, даже плохое ревью лучше, чем его полное отсутствие.
С учетом этих недостатков, спустя какое-то время мы решили все-таки двигаться к полноценному гит-флоу, и этому посвящена последняя глава.
Ssl-ci (Обязательно)
Представляю вам наше сервисное расширение SSL-CI для связи справочника дополнительных отчетов и обработок с гитом.
Это наш внутренний инструмент, которым мы решили поделиться с сообществом 1С.
Что же умеет наше расширение?
По сути это реализация интеграции между конфигурацией 1С с библиотекой БСП (текущая версия режима совместимости Версия 8.3.12) с системой управления репозиториями программного кода (в нашем случае GitLab Community Edition 14.8.4).
Вся интеграция строится на базе публичного api Гитлаба
Как видно из описания расширения на гитхабе (релиз 1.0.2), были реализованы следующие функциональные возможности:
-
Настройка синхронизации с гитом
-
Привязка файла к файлу репозитория
-
Обновление файла из репозитория на последний коммит
-
Обновление всех файлов на последний коммит
-
История коммитов файла
-
Добавление нового файла из репозитория
-
Связка с таск-трекером и коммитом (команды перехода)
-
Выбор ветки для файла
-
Переход на конкретный коммит
-
Переключение веток для всех файлов базы
-
Настройка возможности обновления из файла
-
Вывод информации о результатах автоматического обновления
-
Автоматическое создание новых файлов в сборке
После включения и первоначальной настройки расширения вы получите примерно следующее:
Картинка у вас будет примерно такая
Расскажу подробнее по настройке.
Команда настройки интеграции
Текущие настройки
Адрес гита + токен доступа - нужно обязательно сгенерировать токен для доступа в ваш гитлаб. У нас для этого используется токен служебной учетной записи. Подробно про токены доступа
Для токена нужна указать право api
Ид проекта - это ИД вашего проекта в Гитлабе
Ид проекта
Имя каталога с внешними файлами (фильтр поиска) - нужен для фильтрации списка файлов, получаемого через апи. Также этот параметр используется для автоматического деплоя всех новых отчетов/обработок в базу тестирования в сборках проекта.
У нас все файлы отчетов и обработок, которые должны или могут быть загружены в базу, лежат в отдельном каталоге в репозитории:
Каталог с файлами epf и erf, в настройке нужно указывать его
Адрес таск трекера и Префикс задачи - настройка для работы команд перехода из коммита к задаче. Анализирует текст коммита, если там есть префикс задачи, то переходит к этой задаче в таск трекере.
Ручное добавление файлов - после включения расширения мы, по идее, больше вручную файлы не добавляем/обновляем. Но поскольку всегда что-то может пойти не так, то была добавлена настройка, чтобы вернуть возможность работы с ручным добавлением файлов.
После того как вы укажете все настройки, нужно обязательно проверить их по кнопке “Проверить соединение”.
Результаты проверки соединения
После этого вы сможете привязывать ваш отчет/обработку к файлу в гитлабе.
Для первоначального сопоставления вашего справочника и репозитория была сделана специальная служебная обработка ПервоначальноеСопоставлениеФайловСРепозиторием.epf (но вы всегда можете написать собственную).
Сопоставление файлов в репозитории с файлами в базе. По именам обработок/отчетов
На этом первоначальная настройка закончена.
Ssl-ci. Работа с файлами. Команды
Рассмотрим возможности интеграции с гитом в справочнике
Новые интерфейсные возможности
После включения расширения в форме элемента справочника дополнительные отчеты и обработки появляется новая закладка “Интеграция с git”. На ней мы видим текущее состояние интеграции, а также ряд дополнительных команд.
Флаг “Не обновлять автоматически” не дает обновить отчет/обработку при выполнении команды “Обновить все файлы”
Выбор файла из репозитория для связки с элементом справочника. Ветку можно выбрать любую. Не показываются уже добавленные файлы.
История коммитов. Можно откатить отчет/обработку на любой прошлый коммит
Команда “Обновить все файлы” актуализирует ваш справочник файлов. Как работает актуализация:
-
Получаем все файлы, где указан адрес в репозитории и ветка, “Публикация = Используется” и не стоит галка “Не обновлять автоматически”
-
По каждому файлу получаем из гитлаба последний коммит (с учетом ветки)
-
Если текущий коммит <> последнему коммиту файл обновляется на последний коммит
-
В интерактивном режиме показывается отчет об обновлении
Результат обновления. Когда тут прилетает сразу штук 20 разных отчетов и обработок возможен побочный эффект в виде чувства радости
Команда “Переключить ветку” переключает ветку во всех отчетах и обработках на выбранную
Переключение ветки
При переключении анализируется, существует ли такой файл в выбранной ветке и если существует, то он получается из этой ветки. Игнорирует файлы с галкой “Не обновлять автоматически”.
Команды “Обновить обработку/отчет” и “Переключить ветку файла” работают аналогично, но для конкретного выбранного файла.
Также в коде расширения предусмотрен запрет на переключение ветки для рабочей базы. Этот запрет можно либо не использовать (по умолчанию) либо настроить под свою базу.
Мы у себя смотрим на константу “ЭтоРабочаяБаза”
Ssl-ci. Автодеплой (опционально).
Итак, остался последний шаг. Встроить автоматическое обновление внешних файлов в сборку основного проекта.
Перед каждой сборкой мы обновляем тестовую базу из хранилища с помощью vanessa-runner.
Шаг по обновлению тестовой ИБ
После обновления из хранилища скрипт запускает обновление базы в пользовательском режиме. Описание процесса обновления
Как можно заметить по скрину, вместо команды “@call vrunner run --command "ЗапуститьОбновлениеИнформационнойБазы;ЗавершитьРаботуСистемы;" --execute $runnerRoot\epf\ЗакрытьПредприятие.epf” мы после параметра execute вызываем свою версию обработки для закрытия предприятия.
Она отличается от стандартной наличием такого кода:
т.е. мы сначала получаем все недостающие файлы из ветки develop и актуализируем справочник
Теперь можно покрывать все важные отчеты, обработки и печатные формы сценарными тестами и проверять корректность доработок.
Благодаря автоматическому обновлению мы смогли покрыть сценарными тестами все самые важные внешние отчеты и обработки.
Пример сценария тестирования отчета. Тут все стандартно - формируем отчет и сравниваем с макетом, должны совпадать на исторических данных.
Также, поскольку все внешние файлы уже находятся в вашей базе тестирования в актуальном состоянии, то для дымового тестирования больше не нужно актуализировать файловую шару. Мы у себя написали еще два дымовых теста в этой логике (проверка имени варианта отчета и еще один специфичный).
Итоги
Пока можно зафиксировать промежуточные итоги нашего процесса разработки внешних файлов.
Теперь все внешние файлы у нас разрабатываются по гит-флоу (мы выбрали простой вариант через master/develop и, иногда, фича-ветки.
В рабочую базу изменения попадают только после мерж-реквеста в мастер после прохождения пайплайна тестирования и этапа ревью (автодеплой после успешного мержа у нас пока на стадии проработки).
Само ревью средствами гитлаба намного удобнее единого ежемесячного ревью. Правда формы все равно пока приходится проверять через конфигуратор.
Ну и в целом, как нам кажется, процесс доработки стал более прозрачен и предсказуем.
Буду рад, если наше расширение и подход к разработке кому-то пригодятся.
P.s. В планах есть идея прикрутить и выпуск расширений через Ssl-ci, но пока у нас расширения используются в основном как ХотФиксы, поэтому эти планы не в высоком приоритете.
