03.11.2021

Инструкция по созданию патчей (оперативных исправлений ошибок)

1. Патчи следует выпускать для оперативного исправления критичных ошибок в прикладных решениях и библиотеках, не дожидаясь выпуска очередного исправительного релиза ("минуя" длительную процедуру выпуска и встраивания библиотек – в случае ошибок в библиотеках).

Критичность определяется ответственным за прикладное решение (библиотеку). 

2. Технически патч – это расширение конфигурации, которое имеет небольшой размер (по сравнению с файлом поставки или обновления конфигурации), и установка которого не требует длительного обновления и блокировки работы пользователей. Для применения патча достаточно перезапустить сеанс.

Установка и удаление патчей реализована в 1С:Библиотека стандартных подсистем, а в 1С:Библиотека интернет-поддержки предусмотрена автоматическая загрузка патчей с портала 1C:Обновление программ. Вариант установки патчей (ручной или автоматический) в "коробках" контролирует администратор, а в модели сервиса – администратор сервиса (требуется подключение экземпляра облачного решения 1C:Fresh к порталу 1С:ИТС). Для "коробок" и облачных решений без подключения к интернету также возможно загружать интересующие патчи с портала 1C:Обновление программ на флешку и устанавливать с нее.

3. Создавать патчи можно с помощью конфигуратора или автоматически по исправленным в хранилище ошибкам с помощью 1С:Система проектирования прикладных решений (СППР). С помощью СППР патчи формируются автоматически по закладкам в репозитории git, рассчитывается применимость патча к версиям конфигурации (а для библиотек – к версиям всех прикладных решений, в которые она встроена); автоматизирована публикация и отзыв патчей, есть подписание патчей для базовых версий, а также целый ряд других полезных сервисов.

Создание патчей с помощью конфигуратора

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

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

Для этого создать новое расширение конфигурации (если изменять ранее созданное расширение для другой ошибки, то это приведет к исключению при одновременном подключении этих расширений) и выполнить действия:

1. Указать свойства расширения:   
   • Имя – "EF_<произвольный_номер_ошибки>". Например, EF_00_00268773.    
   • Префикс имен – берется из свойства имя.
   • Основные роли – снять флаг.
   • Основной язык – снять флаг. 
   • В группе Совместимость – снять флаги у всех свойств.
   • Режим совместимости - указывать равный или ниже тому, что у конфигурации, для которого оно создается.
2. Не удалять объект метаданных Язык – Русский.    
3. Перенести изменения в расширение-патч. 
   • Для процедур и функций – встать на любой строчке и нажать ALF+SHIFT+F2, в диалоговом окне "Тип выбора" указать "Вызывать вместо".    
   • В метод патча перенести текущую реализацию со всеми необходимыми изменениями.
4. Создать и заполнить макет, который описывает содержимое патча и информацию о нем:
   • Добавить общий макет, имя которого совпадает с именем расширения. Например, EF_00_00268773.   
   • Заполнить содержимое макета по примеру: 
   Копировать в буфер обмена

   <Patch xmlns="http://www.v8.1c.ru/ssl/patch" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
    <Name>EF_00_00268773</Name>    
    <Description>В веб-клиенте при сохранении некоторых печатных форм может быть недоступен выбор папки сохранения.</Description>    
    <UUID>abfde8f7-7ac4-43a9-9521-d291d0d0d6c3</UUID> 
    <ModifiedMetadata>ОбщаяФорма.СохранениеПечатнойФормы.ПриСозданииНаСервере</ModifiedMetadata> 
    <AppliedFor>    
     <ConfigurationName>СтандартныеПодсистемы</ConfigurationName>    
     <Versions>3.1.2.229,3.1.2.245</Versions>    
    </AppliedFor>
   </Patch>

   где:

   • Name – должно совпадать с именем патча из расширения
   • Description – описание для пользователя, будет отображаться в списке установленных патчей.    
   • UUID – уникальный идентификатор патча.  Требуется создать новый, получив методом платформы Новый УникальныйИдентификатор.    
   • ModifiedMetadata – изменяемые объекты метаданных.    
   • AppliedFor – блок, в котором описывается к каким конфигурациям подходит данный патч.    
   • ConfigurationName – имя конфигурации, берется из описания подсистемы в модуле ОбновлениеИнформационнойБазы<Сокращение>.    
   • Versions – список версий конфигурации через запятую, для которой применим патч.    
   • Рекомендуется при проверке патча проверять, что данный макет корректно читается и в нем нет ошибок – для этого нужно перейти к списку установленных исправлений (Администрирование – Обслуживание – Установленные исправления).

При переносе исправления ошибки в расширение следует учитывать следующее. Новые процедуры и функции следует добавлять в расширение с префиксом патча, например, вместо

"ИмяМоейПроцедуры" следует указывать

"EF_<произвольный_номер_ошибки>_ИмяМоейПроцедуры".

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

Создание патчей с помощью Системы проектирования прикладных решений (СППР)

Первичная настройка

1. Развернуть сервер репозиториев git (например, GitLab) и указать его адрес в карточке проекта в СППР.
   • на закладке Разработка в группе Настройки Git-репозитория указать параметры подключения к репозиторию git, в котором ведется разработка.
     • В параметр Каталог git репозитория должен быть указан путь к сетевой папке, в которой будет храниться копия хранилища для создания патчей. В этой папке должен быть доступ у пользователя, под которым запущен сервер СППР.
     • В параметре Адрес git репозитория на сервере указать путь для подключения к удаленному серверу по протоколу SSH. Например, git@<мой_сервер>:ssl/ssl.git
     • Имя ветки – master.
   • для исправительных версий необходимо указать имя ветки репозитория – перейти к карточке версии и на закладке Разработка заполнить поле "Ветка разработки".
     
   • В настройках удаленного репозитория Git нужно добавить Deploy key для пользователя под которым работает сервер СППР.
     
   • для конвертации хранилища 1С в репозиторий git также использовать 1С:ГитКонвертер.
2. Переключиться на закладку Общая информация проекта и заполнить поля Имя конфигурации – то, что указано в модуле ОбновлениеИнформационнойБазы<Сокращение> и Идентификатор программы – идентификатор в сервисах Интернет-поддержки пользователей. Если СППР будет использоваться только для создания патчей, без их публикации, то идентификатор программы заполнять не обязательно.
   
3. В карточке версии:
   • на закладке Наследование ошибок и патчи включить флажок "Автоматически создавать патчи по публикуемым ошибкам";
   • заполнить поле Версия платформы. Значение должно совпадать с режимом совместимости платформы для данной версии конфигурации.
     

Создание патчей для ошибок

1. Исправить ошибку в хранилище проекта.
2. В карточке ошибки в СППР внизу на закладке Исправление включить флажок Создать патч по исправлению ошибки.
3. Описание патча автоматически заполнится из публикуемого описания ошибки.
4. Дождаться готовности патча, проверить его на версии, в которой ошибка была привнесена, и нажать Проверен в карточке патча (для каждой версии, если патч создается сразу для нескольких версий проекта). 
5. Сформированный патч сохранить по кнопке Сохранить патч… и передать пользователям.
6. Если СППР подключен к базе публикации, то нажать Опубликовать. После чего патч будет отправлен в базу публикации и вскоре окажется доступен для автоматической загрузки с портала 1C:Обновление программ.

Отзыв патчей с портала 1C:Обновление программ

В случае если ошибка исправлена неверно, требуется отозвать патч и выпустить новый. Но не следует перевыпускать патч или выпускать патч на патч.
При публикации патча из СППР необходимо:

1. Открыть карточку интересующего патча. 
2. В меню Еще списка версий патча нажать Отозвать. После чего информация об отзыве патча будет отправлена на портал 1C:Обновление программ.

Если патч публиковался вручную на портале 1C:Обновление программ, то отзыв так же выполняется вручную.

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

Если патч не удалось создавать автоматически

Не во всех случаях возможно создать патч автоматически, например:

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

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

Рекомендации и ограничения технологии патчей

Патчи подходят для исправления ошибок:

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

Патчи не подходят:

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

Один патч должен "точечно" исправлять только одну ошибку

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

Патчи не должны создаваться "внахлест"

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

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

Тщательно проверять патчи

Поскольку патч публикуется максимально оперативно, то рекомендуется дополнительно проверять патч отдельно от проверки исправления ошибки:

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

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

Проверка патча важна в полном объеме, во всех ветках, для которых он будет публиковаться.

Кроме того, для проверки патчей настоятельно рекомендуется:

• аудит исправления ошибки другим разработчиком;
• перекрестная проверка исправления тестировщиком или другим разработчиком.

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

Патч рекомендуется публиковать только после выполнения перечисленных этапов проверки.

Подпись патчей для базовых версий конфигураций

<путь к платформе> DESIGNER /IBConnectionString <строка подключения> /SignCfg <путь к подписанному патчу> -Type File -digisign <путь к закрытому ключу (*.pem)> -File <путь к исходному патчу>