Введение

Здесь представлена рекомендуемая методология разработки, сопровождения и управления версиями приложений в Comindware Platform.

Методология описывает общий процесс управления версиями, ветками, средами и релизами в Git. Данные принципы и подходы также применимы при управлении версиями с помощью файлов CTF и Excel.

Методология дополняет функциональные инструкции из статей:

Подробные пошаговые инструкции по экспорту и импорту версий приложений в Comindware Platform см. в соответствующих статьях.

Среды и ветки

Рекомендуемые среды

Для разработки приложения в Comindware Platform рекомендуется использовать как минимум две среды:

• среда разработки — экземпляр Comindware Platform, на котором выполняются настройка, отладка и проверка изменений;
• продуктивная среда — экземпляр Comindware Platform, на котором приложение используется конечными пользователями.

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

При необходимости можно использовать дополнительные среды (например, тестовую или предпродуктивную), однако базовый принцип остаётся неизменным:

• изменения в приложение сначала необходимо вносить и тестировать в отдельной среде;
• только после тестирования в отдельной среде изменения допустимо переносить в продуктивную среду.

Рекомендуемая схема веток

В Git рекомендуется настроить репозиторий с как минимум двумя ветками:

• рабочая ветка разработки (например, develop) — для текущих изменений и интеграции задач;
• стабильная ветка продуктивных версий (например, main) — для версий, которые развернуты или запланированы к развертыванию в продуктивной среде.

В базовой схеме экземпляр Comindware Platform среды разработки связан с рабочей веткой, а продуктивный экземпляр — со стабильной веткой. При этом:

1. Изменения фиксируются в рабочей ветке.
2. Перед выпуском новой версии приложения изменения из рабочей ветки объединяются со стабильной веткой.
3. Импорт в продуктивную среду выполняется из стабильной ветки.

Запрет прямых изменений в продуктивной среде

Придерживайтесь следующих правил:

• Выполняйте настройку приложения только в среде разработки.
• Вносите любые изменения конфигурации в продуктивной среде только в исключительных случаях, после чего воспроизводите их в среде разработки и переносите через механизм управления версиями.
• Не используйте стабильную ветку репозитория (например, main или master) для непосредственной разработки — вносите изменения в неё только через слияние из рабочей ветки (например, develop).
• После слияния рабочей и стабильной веток обновляйте продуктивную среду, выполнив импорт подготовленной версии приложения из стабильной ветки.

Цикл настройки приложения

Допустимые типы изменений

В рамках одного цикла настройки могут изменяться различные параметры конфигурации и элементы приложения, в том числе:

• бизнес-процессы и диаграммы процессов;
• формы и правила для форм;
• таблицы и фильтры;
• атрибуты и вычисления;
• шаблоны записей, включая справочники;
• сценарии и параметры приложения;
• разделы навигации и страницы.

Логически завершённые изменения

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

Для каждого блока:

• формулируйте цель (например, реализация конкретной задачи или пользовательского сценария);
• не смешивайте изменения с другими, не связанными задачами;
• обеспечьте возможность проверки результата отдельно от других работ.

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

Проверка изменений в среде разработки

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

Проверьте:

• корректность выполнения процессов;
• отображение форм и таблиц;
• работа правил для форм;
• работоспособность сценариев;
• работоспособность интеграций;
• воспроизведение ключевых пользовательских сценариев;
• другие функции приложения.

При выявлении ошибок внесите исправления и повторите цикл проверки.

Фиксация изменений (коммиты)

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

1. Экспортируйте приложение в репозиторий из среды разработки.
2. Создайте коммит с конфигурацией приложения в выбранной ветке.

Сообщение коммитов представляет собой описание версии приложения.

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

• указывать номер задачи из системы управления задачами;
• кратко описывать изменённый функционал или область приложения.

При ручном экспорте в файл CTF или Excel:

• используйте понятную схему именования файлов и каталогов, например кратко указывайте номера задач, релизов, версий и цели изменений.
• сохраняйте в папке с экспортированным файлом текстовый файл с кратким описанием версии.

Подготовка и перенос изменений в продуктивную среду

Подготовка к релизу

Перед переносом изменений в продуктивную среду:

1. Убедитесь, что рабочая ветка с изменениями актуальна и включает все необходимые коммиты.
2. Согласуйте с командой параллельные работы (если их невозможно остановить), чтобы избежать конфликтов и неожиданных изменений.
3. Зафиксируйте состав изменений, входящих в релиз (например, список задач или требований).
4. Сопоставьте изменения в конфигурации приложения с выбранными коммитами и убедитесь, что в релиз не попадают изменения, не относящиеся к задачам этого релиза.

Слияние веток для формирования релиза

Типовой порядок действий:

1. Подготовьте изменения в рабочей ветке (например, develop) и убедитесь, что они успешно проходят проверку в среде разработки.
2. Создайте запрос на слияние (pull request) из рабочей ветки в стабильную ветку (например, main).
3. Проанализируйте список изменений и при необходимости устраните конфликты.
4. Выполните слияние в стабильную ветку.
5. Установите тег версии в стабильной ветке (см. раздел «Версионирование и откат»).

Обновление продуктивной среды

1. Убедитесь, что для продуктивной среды настроено и выполняется регулярное резервное копирование, и перед обновлением создана наиболее актуальная резервная копия. См. «Резервное копирование и восстановление. Рекомендации по организации и оптимизации».
2. Сформируйте новую версию приложения в среде разработки.
3. Выполните шаги, указанные в статье «Подготовка приложения к экспорту».
4. Перенесите новую версию приложения в продуктивную среду.
5. Выполните проверки по заранее подготовленным тест-кейсам или контрольным спискам.

Контрольные списки релиза и отката

Перед релизом (обновлением продуктивной среды):

1. Протестируйте релизную версию приложения в среде разработки.
2. Зафиксируйте и согласуйте состав изменений (список задач и требований без случайных правок).
3. Оцените риски и подготовьте план отката (определите предыдущую стабильную версию).
4. Согласуйте окно работ и при необходимости подготовьте резервную копию продуктивной среды.

После релиза:

1. Проверьте ключевые пользовательские сценарии в продуктивной среде по чек-листу.
2. Просмотрите журналы экспорта/импорта и системные логи на наличие критичных ошибок.
3. Обновите документацию решения и журнал версий (номер версии, дата, краткое описание изменений).
4. Примите и зафиксируйте решение о статусе релиза (успешен, требуется корректирующий релиз или откат).

Версионирование и откат

Фиксация версий приложения

Каждое обновление продуктивной среды рекомендуется рассматривать как отдельную версию приложения.

При использовании Git это обычно реализуется с помощью тегов в стабильной ветке. Например:

• тег содержит номер версии приложения и при необходимости краткое описание;
• тег ставится на коммит, соответствующий версии, развернутой в продуктивной среде.

Кроме того, номер версии следует фиксировать в сопровождающей документации версии и, при необходимости, в самом приложении.

Откат к предыдущей версии

При использовании Git откат версии конфигурации в репозитории выполняется на стороне системы контроля версий, а в Comindware Platform импортируется соответствующая версия приложения. При использовании файла CTF или Excel, выполняется импорт требуемой версии.

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

1. Определите целевую версию (тег, номер или коммит, соответствующий стабильному состоянию приложения).
2. Оцените влияние отката на данные, связанные приложения и интеграции.
3. Подготовьте конфигурацию этой версии.
4. Обеспечьте возможность вернуться даже от неудачного отката (подготовьте резервную копию текущего состояния).
5. Согласуйте план отката и коммуникации с пользователями.
6. Импортируйте выбранную версию в продуктивную среду.
7. Проверьте работоспособность ключевых пользовательских сценариев на откатанной версии.
8. Зафиксируйте причины отката и план последующих действий (исправления, новый релиз).
9. Обновите журнал версий и документацию (к какой версии вернулись, когда и почему).
10. Снимите или пересмотрите временные ограничения и временные меры, введённые на время инцидента.

Особенности и ограничения импорта и экспорта версий приложения

Общие особенности поведения при экспорте и импорте, а также перечень сущностей, которые переносятся или не переносятся, подробно описаны в статье «Управление версиями приложения. Экспорт и импорт».

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

• шаблоны, отсутствующие в импортируемой версии, но присутствующие в текущем приложении, могут быть признаны неактуальными и удалены вместе с записями;
• некоторые сущности не экспортируются и должны настраиваться отдельно (например, аккаунты, группы, системные роли, подключения, отдельные пути передачи данных и элементы навигации);
• при импорте переносятся опубликованные диаграммы процессов, при этом старые экземпляры процессов продолжают выполняться по прежним версиям диаграмм;
• обсуждения и часть истории могут не переноситься.

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

Подробную информацию о влиянии экспорта и импорта на идентификаторы и системные имена см. в статье «Идентификаторы и системные имена».

Типовые ошибки и рекомендации по их предотвращению

В процессе управления версиями приложений часто встречаются следующие ситуации:

• попытка экспорта или импорта при некорректных настройках подключения к репозиторию или ограничениях доступа;
• отсутствие фактических изменений в конфигурации приложения при попытке выполнить экспорт;
• использование идентификаторов объектов в выражениях вместо системных имён; идентификаторы могут стать недействительными после импорта в другой экземпляр Comindware Platform;
• экспорт приложений со связанными шаблонами из других приложений без предварительной подготовки;
• смешивание нескольких несвязанных задач в одном релизе или коммите, что усложняет анализ и откат;
• выполнение изменений непосредственно в стабильной ветке репозитория (например, main) вместо слияния из рабочей ветки.

Чтобы снизить риски:

• заранее готовьте приложения к экспорту согласно разделу «Подготовка приложения к экспорту»;
• используйте системные имена вместо идентификаторов в выражениях, когда это возможно;
• разбивайте крупные изменения на несколько версий с промежуточными проверками;
• избегайте выполнения настройки непосредственно на продуктивной среде;
• фиксируйте информацию о составе изменений каждой версии.

Подключение управления версиями к уже работающему продуктиву

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

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

• создайте резервную копию продуктивного экземпляра Comindware Platform;
• разверните копию на отдельном сервере или в отдельном экземпляре, руководствуясь рекомендациями по резервному копированию и восстановлению.

2. Настройте подключение к репозиторию Git, если планируется использование Git. См. статью «Управление версиями через Git. Настройка подключения».
3. Попробуйте выполнить экспорт приложения.
4. Устраните в среде разработки ошибки и несоответствия, препятствующие экспорту приложения.
5. Включите управление версиями для приложения и выполните первый экспорт в репозиторий или в файл версии.
6. Начните использовать описанную в этой статье методологию для дальнейших изменений и релизов.

Такой подход позволяет максимально безопасно перевести уже используемое приложение на управление версиями без прямых экспериментов в продуктивной среде.