97 lines
4.8 KiB
Plaintext
97 lines
4.8 KiB
Plaintext
/**
|
||
@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`.
|
||
*/
|