docs: опиши работу с сабмодулями и добавь сборку Doxygen
This commit is contained in:
27
Doxyfile
Normal file
27
Doxyfile
Normal file
@@ -0,0 +1,27 @@
|
||||
PROJECT_NAME = "templates"
|
||||
PROJECT_BRIEF = "Переносимые библиотеки и правила интеграции"
|
||||
OUTPUT_DIRECTORY = .codex-build/doxygen
|
||||
CREATE_SUBDIRS = NO
|
||||
OUTPUT_LANGUAGE = Russian
|
||||
INPUT = README.md NEW_PROJECT.md CONTRIBUTING.md doc/submodules.dox c python
|
||||
FILE_PATTERNS = *.h *.c *.dox *.md
|
||||
RECURSIVE = YES
|
||||
USE_MDFILE_AS_MAINPAGE = README.md
|
||||
MARKDOWN_SUPPORT = YES
|
||||
AUTOLINK_SUPPORT = YES
|
||||
EXTRACT_ALL = NO
|
||||
EXTRACT_STATIC = NO
|
||||
SOURCE_BROWSER = YES
|
||||
INLINE_SOURCES = NO
|
||||
STRIP_FROM_PATH = .
|
||||
GENERATE_HTML = YES
|
||||
HTML_OUTPUT = html
|
||||
GENERATE_TREEVIEW = YES
|
||||
DISABLE_INDEX = NO
|
||||
GENERATE_LATEX = NO
|
||||
QUIET = YES
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = NO
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_AS_ERROR = FAIL_ON_WARNINGS
|
||||
HAVE_DOT = NO
|
||||
185
NEW_PROJECT.md
185
NEW_PROJECT.md
@@ -120,3 +120,188 @@ USB gs_usb и конкретной разводки адаптера; перен
|
||||
|
||||
Так новый проект не является копией старого: он использует общие ядра одной
|
||||
версии, а аппаратные отличия видны в одном небольшом каталоге `port/`.
|
||||
|
||||
## Слияние и обновление `templates` как Git submodule
|
||||
|
||||
### Что именно хранит основной проект
|
||||
|
||||
Основной проект не хранит содержимое `lib/templates` в своей истории. Вместо
|
||||
этого он хранит **gitlink** — ссылку на один конкретный commit репозитория
|
||||
`templates`. Поэтому при работе есть два независимых уровня истории:
|
||||
|
||||
1. изменения библиотек сливаются и публикуются в репозитории `templates`;
|
||||
2. основной проект отдельным коммитом переводит gitlink на проверенную ревизию
|
||||
`templates`.
|
||||
|
||||
Обычный `git merge` в основном проекте не переносит исходники между ветками
|
||||
`templates` и не создаёт merge-коммит внутри сабмодуля. Он может только выбрать
|
||||
одну из уже существующих ссылок на commit. Если ссылки разошлись, сначала нужно
|
||||
получить общий commit в самом `templates`, а затем зафиксировать его в основном
|
||||
проекте.
|
||||
|
||||
Текущую зафиксированную ревизию удобно смотреть из корня основного проекта:
|
||||
|
||||
```bash
|
||||
git submodule status lib/templates
|
||||
git diff --submodule=log
|
||||
```
|
||||
|
||||
Символ `-` перед SHA в `git submodule status` означает, что сабмодуль ещё не
|
||||
инициализирован; `+` — что рабочая копия сабмодуля находится не на том commit,
|
||||
который записан в основном проекте; `U` — конфликт gitlink.
|
||||
|
||||
### Клонирование проекта и переключение его веток
|
||||
|
||||
Новый клон лучше сразу создавать вместе с сабмодулями:
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules <url-основного-проекта>
|
||||
cd <основной-проект>
|
||||
```
|
||||
|
||||
Если проект уже клонирован:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
После `git switch`, `git checkout`, `git pull` или завершения слияния основной
|
||||
проект может начать ссылаться на другую ревизию `templates`. Рабочее дерево
|
||||
сабмодуля следует явно привести к записанному состоянию:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Это нормальный и воспроизводимый режим: внутри `lib/templates` обычно будет
|
||||
detached HEAD, потому что проект фиксирует commit, а не ветку. Не следует делать
|
||||
там `git pull`, пока не выбрана рабочая ветка и не понятно, какую ревизию должен
|
||||
получить основной проект.
|
||||
|
||||
### Обычное обновление проекта на новую версию `templates`
|
||||
|
||||
Сначала изменение должно быть проверено, закоммичено, отправлено и слито в
|
||||
целевую ветку самого репозитория `templates`. После этого из корня основного
|
||||
проекта выполняется:
|
||||
|
||||
```bash
|
||||
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): обновить общие библиотеки"
|
||||
```
|
||||
|
||||
Перед коммитом нужно собрать основной проект и прогнать его тесты: успешные
|
||||
тесты в `templates` подтверждают работу библиотеки, но не проверяют конкретный
|
||||
порт, настройки платы и интеграцию приложения.
|
||||
|
||||
Коммит основного проекта содержит только переход со старого SHA сабмодуля на
|
||||
новый. Случайные незакоммиченные файлы внутри `lib/templates` в него не входят.
|
||||
Проверить оба уровня перед фиксацией можно так:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git -C lib/templates status
|
||||
git diff --submodule=log
|
||||
```
|
||||
|
||||
Не нужно обновлять сабмодуль на последний `master` автоматически при каждой
|
||||
сборке. Зафиксированный SHA нужен именно для того, чтобы одна и та же версия
|
||||
проекта всегда собиралась с одной и той же версией библиотек.
|
||||
|
||||
### Если библиотеку правят из рабочего дерева основного проекта
|
||||
|
||||
Нельзя коммитить изменение, оставаясь на detached HEAD: такой commit легко
|
||||
потерять при следующем `git submodule update`. Сначала внутри сабмодуля создаётся
|
||||
обычная ветка:
|
||||
|
||||
```bash
|
||||
git -C lib/templates fetch origin
|
||||
git -C lib/templates switch -c feat/<имя> origin/master
|
||||
```
|
||||
|
||||
Затем изменения коммитятся и отправляются именно в репозиторий `templates`:
|
||||
|
||||
```bash
|
||||
git -C lib/templates add <файлы>
|
||||
git -C lib/templates commit -m "feat(<библиотека>): <описание>"
|
||||
git -C lib/templates push -u origin feat/<имя>
|
||||
```
|
||||
|
||||
После проверки ветка сливается в `master` репозитория `templates`. Только после
|
||||
публикации итогового commit основной проект обновляет свой gitlink по процедуре
|
||||
из предыдущего раздела. Не следует отправлять в общий основной проект ссылку на
|
||||
commit сабмодуля, которого ещё нет на сервере: остальные разработчики и CI не
|
||||
смогут его получить.
|
||||
|
||||
### Что происходит при слиянии веток основного проекта
|
||||
|
||||
Возможны три ситуации:
|
||||
|
||||
1. Gitlink изменён только в одной ветке. Git обычно принимает эту ревизию
|
||||
автоматически. После merge нужно выполнить `git submodule update` и тесты.
|
||||
2. Обе ветки указывают на разные commits, но один commit `templates` является
|
||||
предком другого. Следует выбрать более новый проверенный commit, выполнить
|
||||
`git add lib/templates` и продолжить merge.
|
||||
3. Обе ветки указывают на расходящиеся commits `templates`. Это настоящий
|
||||
конфликт истории сабмодуля: выбирать один SHA наугад нельзя, потому что так
|
||||
потеряются изменения второй ветки.
|
||||
|
||||
При конфликте сначала смотрят, какие ссылки пришли с обеих сторон:
|
||||
|
||||
```bash
|
||||
git ls-files -u lib/templates
|
||||
git -C lib/templates fetch origin
|
||||
git -C lib/templates log --oneline --graph --decorate --all
|
||||
```
|
||||
|
||||
Затем в отдельной ветке **репозитория `templates`** объединяют оба commit,
|
||||
устраняют конфликты исходников, запускают тесты и публикуют результат:
|
||||
|
||||
```bash
|
||||
git -C lib/templates switch -c merge/<имя> <sha-одной-стороны>
|
||||
git -C lib/templates merge <sha-другой-стороны>
|
||||
# исправить конфликты и запустить тесты templates
|
||||
git -C lib/templates add <исправленные-файлы>
|
||||
git -C lib/templates commit
|
||||
git -C lib/templates push -u origin merge/<имя>
|
||||
```
|
||||
|
||||
Если общий merge-коммит уже существует в `origin/master`, создавать ещё один не
|
||||
нужно: достаточно выбрать существующий SHA. После получения итогового commit
|
||||
конфликт завершается на уровне основного проекта:
|
||||
|
||||
```bash
|
||||
git -C lib/templates switch --detach <итоговый-sha>
|
||||
git add lib/templates
|
||||
git diff --cached --submodule=log
|
||||
git merge --continue
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
`git add lib/templates` здесь отмечает разрешённым именно gitlink. Не нужно
|
||||
удалять каталог, копировать библиотеку поверх него или разрешать конфликт как
|
||||
обычный текстовый файл.
|
||||
|
||||
### Что должно попасть в merge request основного проекта
|
||||
|
||||
Перед отправкой результата следует проверить:
|
||||
|
||||
1. итоговый commit `templates` доступен в удалённом репозитории;
|
||||
2. `git -C lib/templates status` не показывает локальных изменений;
|
||||
3. `git submodule status` не начинается с `+`, `-` или `U`;
|
||||
4. `git diff --submodule=log <целевая-ветка>...HEAD` показывает ожидаемый набор
|
||||
commits библиотек;
|
||||
5. тесты `templates`, сборка основного проекта и проверки на целевой плате
|
||||
прошли;
|
||||
6. в основном проекте закоммичены необходимые изменения адаптеров, конфигурации
|
||||
и сам новый gitlink.
|
||||
|
||||
После получения ветки другой разработчик восстанавливает ровно выбранное
|
||||
состояние одной командой:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
@@ -69,6 +69,11 @@ templates/
|
||||
В ней отдельно описаны граница ядра, ABI, память, три wire format и состояние
|
||||
портов Windows, Android, Linux и MCU.
|
||||
|
||||
Обзор всего репозитория, включая слияние при подключении через submodule:
|
||||
[`doc/index.html`](doc/index.html). Справочник Doxygen собирается командой
|
||||
`powershell -ExecutionPolicy Bypass -File doc/build-doxygen.ps1` в
|
||||
`.codex-build/doxygen/html/index.html`.
|
||||
|
||||
## Как подключить к проекту
|
||||
|
||||
**Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
|
||||
@@ -78,6 +83,10 @@ git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Как обновлять зафиксированную ревизию, переносить изменения из проекта и
|
||||
разрешать конфликт gitlink при слиянии веток, подробно описано в разделе
|
||||
[`Слияние и обновление templates как Git submodule`](NEW_PROJECT.md#слияние-и-обновление-templates-как-git-submodule).
|
||||
|
||||
Дальше в сборку добавляются только нужные каталоги:
|
||||
|
||||
```
|
||||
|
||||
28
doc/build-doxygen.ps1
Normal file
28
doc/build-doxygen.ps1
Normal file
@@ -0,0 +1,28 @@
|
||||
[CmdletBinding()]
|
||||
param()
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$repositoryRoot = Split-Path -Parent $PSScriptRoot
|
||||
$doxygen = Get-Command doxygen -ErrorAction SilentlyContinue
|
||||
|
||||
if (-not $doxygen) {
|
||||
throw 'Doxygen не найден в PATH. Установите Doxygen и повторите запуск.'
|
||||
}
|
||||
|
||||
Push-Location $repositoryRoot
|
||||
try {
|
||||
& $doxygen.Source Doxyfile
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
throw "Doxygen завершился с кодом $LASTEXITCODE."
|
||||
}
|
||||
}
|
||||
finally {
|
||||
Pop-Location
|
||||
}
|
||||
|
||||
$indexPath = Join-Path $repositoryRoot '.codex-build\doxygen\html\index.html'
|
||||
if (-not (Test-Path -LiteralPath $indexPath)) {
|
||||
throw "Doxygen не создал ожидаемый файл: $indexPath"
|
||||
}
|
||||
|
||||
Write-Host "[DONE] Doxygen HTML: $indexPath"
|
||||
File diff suppressed because one or more lines are too long
96
doc/submodules.dox
Normal file
96
doc/submodules.dox
Normal file
@@ -0,0 +1,96 @@
|
||||
/**
|
||||
@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`.
|
||||
*/
|
||||
Reference in New Issue
Block a user