/change-package - пакет ручного внесения изменений
Берет две версии модулей - до и после - и превращает разницу в инструкцию, которую человек выполняет в Конфигураторе: по каждому методу что найти и на что заменить целиком.
Правка при этом делается уже в базе, а не в исходниках. Навык не открывает платформу, не запускает базу и ничего не меняет ни в одной из версий: он только читает файлы и пишет markdown.
Когда применять
- объект на поддержке с запретом изменения - исходники недоступны на запись;
- модуль захвачен другим пользователем в хранилище конфигурации;
- форма обычная (не управляемая): в исходниках ей соответствует
.form, а не.xml, и собирается она только Конфигуратором; - у пользователя есть база и Конфигуратор, но нет доступа к выгрузке исходников;
- правку выполняет человек: агент готовит текст, но не применяет его.
Когда не применять
| Ситуация | Чем решать |
|---|---|
| Право правки исходников есть | обычная правка модуля: 1c-meta-edit, 1c-form-edit или редактор |
| Доработку типовой оформляют расширением | 1c-cfe-init, 1c-cfe-borrow, 1c-cfe-patch-method |
| Нужно сравнить конфигурацию с расширением | 1c-cfe-diff |
| Нужен построчный diff для чтения человеком | git diff или diff-инструмент, разбор по методам не нужен |
| Правка уже сделана в исходниках | ничего: база обновляется загрузкой выгрузки |
Пакет - обходной путь. Он имеет смысл, только когда исходники недоступны; в остальных случаях правка исходников дешевле и не требует ручной работы.
Параметры
| Параметр | Обяз. | Описание |
|---|---|---|
-Before | да | Файл или каталог до правки |
-After | да | Файл или каталог после правки |
-OutFile | нет | Куда записать пакет. Без него пакет печатается в stdout |
-Before и -After должны быть однотипными: либо два файла, либо два каталога. Каталоги
сверяются как выгрузки конфигурации (Catalogs/Товары/Ext/ObjectModule.bsl) и сопоставляются по
относительному пути; сравниваются только модули .bsl, остальные различия попадают в список для
ручной правки.
Тип объекта и вид модуля берутся из пути, поэтому подписи в пакете зависят от раскладки выгрузки:
Catalogs/Товары/Ext/ObjectModule.bsl дает "Справочник Товары, модуль объекта". Незнакомый каталог
или незнакомое имя файла оставляют в заголовке только путь - разбор методов от этого не страдает.
Команда
powershellpowershell.exe -NoProfile -File "skills/1c-change-package/scripts/change-package.ps1" -Before "src-old" -After "src-new" -OutFile "package.md"
bashpython skills/1c-change-package/scripts/change-package.py -Before src-old -After src-new -OutFile package.md
Оба порта дают байт-в-байт одинаковый пакет: UTF-8 без BOM, перевод строки LF. Это закреплено кейсами, поэтому пакет можно передавать человеку независимо от того, чем он собран.
Что в пакете
| Место в файле | Что там |
|---|---|
| Шапка | Пути, счетчики: модулей с правками, методов изменено, добавлено, удалено, правок вне методов, замен целиком |
## <путь> - <объект> | Раздел модуля. Один пункт - одно действие |
### Изменить метод <Имя> | Блоки Найти: и Заменить целиком на: с текстом метода |
### Добавить метод <Имя> перед методом <Соседний> | Блок Текст метода:. Место вставки задает метод старой версии: новый метод ставится перед ним |
### Добавить метод <Имя> после метода <Соседний> | То же для метода, который в новой версии идет последним |
### Удалить метод <Имя> | Блок Удалить целиком: |
### Изменить код вне методов <привязка> | Блоки Найти: и Заменить целиком на: для одного смежного участка кода вне методов. Привязка - в начале модуля, в конце модуля или после метода <Имя> |
### Заменить модуль целиком | Блоки Найти: и Заменить целиком на: со всем модулем. Пункт заменяет остальные, когда однозначный фрагмент Найти построить нельзя |
### Порядок методов изменен | Примечание без блоков: методы те же, но идут в другом порядке, текст переносится как есть |
## Файлы для правки вручную | Файлы, которые не .bsl, а также новые и удаленные файлы |
Метод отдается целиком, вместе с директивой компиляции и комментарием перед объявлением: замена идет по методу, а не по отдельной строке.
Поиск в Конфигураторе ведется по блоку Найти: из старой версии, поэтому фрагмент обязан быть
единственным в модуле: повторяющийся фрагмент навык в пакет не ставит, такой модуль помечается
как ### Заменить модуль целиком. По той же причине целиком заменяется модуль, у которого
участок кода вне методов есть только в одной из версий: привязать такой участок к соседнему
методу однозначно нельзя. Замена целиком - не ошибка навыка, а признак того, что безопаснее
перенести модуль как есть.
Код вне методов разбит на смежные участки, у каждого свой пункт и своя привязка: один поиск в Конфигураторе не находит строки, между которыми стоит метод. Участок из одних пустых строк пункта не дает: перестановка пустых строк правкой не считается.
Порядок пунктов повторяет порядок методов в новой версии, поэтому пакет можно выполнять сверху вниз, не возвращаясь назад.
Ограничения разбора
Навык разбирает модуль по объявлениям методов и не анализирует код внутри. Отсюда следствия, которые важно понимать, прежде чем отдавать пакет человеку:
- переименование метода выглядит как удаление одного и добавление другого, а не как правка;
- правка внутри метода показывается заменой метода целиком, даже если изменилась одна строка: это осознанно - такую замену механически выполняет и человек, и сама платформа;
- директива компиляции попадает в тот метод, объявление которого идет следом: строка примыкает к объявлению, поэтому показывается вместе с методом, а не в блоке вне методов;
- комментарий перед объявлением показывается вместе с методом и тогда, когда в другой версии он отделен от объявления пустой строкой: в блоке замены комментарий не теряется;
- объявление
Асинх Процедура(Async Procedure) разбирается так же, как обычное: закрывающее слово метода берется из его ключевого слова; - метод, объявление которого охвачено веткой
#Если, показывается вместе с ветками#Иначеи#КонецЕсли: конец метода - закрывающая строка препроцессора, поэтому в блоке видно несколькоКонецПроцедуры, по одному на ветку; - разбор идет по ключевым словам обоих написаний, русского и английского: модуль на английском BSL разбирается так же, как русский.
Пакет не проверяет, что правка применится к той версии модуля, которая лежит в базе: сверять
блок Найти: с фактическим текстом модуля - дело того, кто выполняет правку.
Проверка на реальных данных
Ручную приемку делает человек: пакет строится по файлам, а применяется в Конфигураторе. Перед
выдачей пакета убедиться, что версия -Before совпадает с модулем в базе - иначе блок Найти:
не будет найден.
Связанные навыки
1c-cfe-diff- сравнение конфигурации с расширением: показывает, что уже перенесено1c-cfe-patch-method- перехват метода расширением, когда исходники менять не нужно1c-config-index- индекс выгрузки: пути модулей и имена объектов
