/**
@page submodule_workflow Слияние templates как Git submodule

Основной проект хранит не файлы `templates`, а gitlink: ссылку на один точный
commit отдельного репозитория. Поэтому слияние выполняется на двух уровнях:

1. исходники и их конфликты объединяются в репозитории `templates`;
2. основной проект отдельным commit фиксирует итоговый SHA сабмодуля.

@section submodule_clone Клонирование и переключение веток

Новый проект клонируется вместе с сабмодулями:

@code{.sh}
git clone --recurse-submodules <url-основного-проекта>
@endcode

После `git switch`, `git pull` или merge рабочее дерево приводится к gitlink,
который записан в выбранной ревизии проекта:

@code{.sh}
git submodule update --init --recursive
@endcode

Detached HEAD внутри `lib/templates` в этом режиме является нормой: основной
проект фиксирует commit, а не плавающую ветку.

@section submodule_update Обновление зафиксированной версии

Изменение сначала должно быть проверено и слито в `master` репозитория
`templates`. Затем основной проект выбирает опубликованный commit:

@code{.sh}
git -C lib/templates fetch origin
git -C lib/templates switch --detach origin/master
git add lib/templates
git diff --cached --submodule=log
git commit -m "build(templates): обновить общие библиотеки"
@endcode

Перед commit проверяются тесты самой библиотеки, сборка проекта, адаптеры,
конфигурация платы и аппаратные тесты. Автоматически двигать сабмодуль на
последний `master` при каждой сборке не следует: это уничтожает
воспроизводимость.

@section submodule_develop Изменение templates из основного проекта

Перед редактированием нужно выйти из detached HEAD в обычную ветку:

@code{.sh}
git -C lib/templates fetch origin
git -C lib/templates switch -c feat/<имя> origin/master
@endcode

Commit и ветка отправляются в удалённый репозиторий `templates`. Основной
проект обновляет gitlink только после публикации итогового SHA, иначе коллеги
и CI не смогут получить указанную ревизию.

@section submodule_conflict Разрешение конфликта gitlink

Если ветки основного проекта указывают на расходящиеся commits сабмодуля,
выбирать `ours` или `theirs` наугад нельзя. Сначала определяются обе ссылки:

@code{.sh}
git ls-files -u lib/templates
git -C lib/templates fetch origin
git -C lib/templates log --oneline --graph --decorate --all
@endcode

Оба commit объединяются и тестируются в отдельной ветке репозитория
`templates`. После публикации общего commit конфликт завершается в основном
проекте:

@code{.sh}
git -C lib/templates switch --detach <итоговый-sha>
git add lib/templates
git diff --cached --submodule=log
git merge --continue
git submodule update --init --recursive
@endcode

`git add lib/templates` отмечает разрешённым gitlink. Удалять каталог или
копировать в него файлы для разрешения конфликта не требуется.

@section submodule_checklist Проверка перед merge request

- итоговый commit `templates` опубликован;
- `git -C lib/templates status` не показывает локальных изменений;
- `git submodule status` не начинается с `+`, `-` или `U`;
- `git diff --submodule=log` показывает ожидаемое обновление;
- тесты библиотек, сборка основного проекта и проверка платы прошли;
- изменения адаптеров и новый gitlink закоммичены в основном проекте.

Полная инструкция с разбором всех трёх вариантов merge находится в
`NEW_PROJECT.md`.
*/