крупное обновление документации
This commit is contained in:
@@ -0,0 +1,343 @@
|
||||
# Командная разработка OpenWC
|
||||
|
||||
## Цель
|
||||
|
||||
Этот workflow позволяет нескольким людям и Codex-агентам работать параллельно, не перезаписывая изменения друг друга и не разрушая архитектурные границы. Единица параллельной работы — не milestone целиком, а ограниченный `work package`.
|
||||
|
||||
## Основные правила
|
||||
|
||||
1. Каждый агент работает в отдельном clone или Git worktree и собственной ветке.
|
||||
2. Никто не разрабатывает напрямую в `master`.
|
||||
3. До изменений задача получает ID, владельца, claim и список затрагиваемых путей.
|
||||
4. Один work package имеет только одного активного владельца.
|
||||
5. Общие contracts согласуются до параллельной реализации producers/consumers.
|
||||
6. Статус milestone и `OPENWC_TARGET_DONE` изменяет только интегратор.
|
||||
7. Merge выполняется только после handoff, локальных проверок и синхронизации с актуальным `master`.
|
||||
|
||||
## Идентификаторы
|
||||
|
||||
### Agent ID
|
||||
|
||||
Каждый человек/агент выбирает стабильный ID на весь work package:
|
||||
|
||||
```text
|
||||
<human>-<machine>-codex
|
||||
```
|
||||
|
||||
Примеры:
|
||||
|
||||
```text
|
||||
sindo-main-codex
|
||||
alex-laptop-codex
|
||||
```
|
||||
|
||||
ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто `codex`, потому что таких агентов несколько.
|
||||
|
||||
### Work Package ID
|
||||
|
||||
```text
|
||||
<TARGET>-<PROGRAM>-<SHORT-NAME>-<NNN>
|
||||
```
|
||||
|
||||
Примеры:
|
||||
|
||||
```text
|
||||
M01-FND-COORDS-001
|
||||
M03-RND-SCHEDULER-001
|
||||
M08-NET-SRP-001
|
||||
M12-UIA-LUA-SPIKE-001
|
||||
```
|
||||
|
||||
Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).
|
||||
|
||||
## Claim protocol
|
||||
|
||||
Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в `coordination/claims/`, который сначала публикуется в общей ветке.
|
||||
|
||||
Claim marker:
|
||||
|
||||
```text
|
||||
<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-13 -->
|
||||
```
|
||||
|
||||
Последнее поле — дата истечения claim в UTC. Рекомендуемый срок — 48 часов; владелец продлевает его коротким status update. Истёкший claim нельзя забирать молча: сначала оставить сообщение владельцу и интегратору.
|
||||
|
||||
Claim содержит:
|
||||
|
||||
- target и work package;
|
||||
- owner/agent ID;
|
||||
- outcome и non-goals;
|
||||
- exclusive paths;
|
||||
- shared/hotspot paths;
|
||||
- contracts/schema/format changes;
|
||||
- dependencies и blockers;
|
||||
- verification commands;
|
||||
- expected fidelity evidence.
|
||||
- documentation deliverables: inline API, module spec, diagrams и source map.
|
||||
|
||||
## Ветки и worktrees
|
||||
|
||||
Имя ветки:
|
||||
|
||||
```text
|
||||
work/<agent-id>/<target>-<short-name>
|
||||
```
|
||||
|
||||
Пример:
|
||||
|
||||
```text
|
||||
work/sindo-main-codex/m01-coordinate-mapper
|
||||
```
|
||||
|
||||
Начало работы:
|
||||
|
||||
```powershell
|
||||
git fetch origin
|
||||
git worktree add ..\open-wc-m01 -b work/sindo-main-codex/m01-coordinate-mapper origin/master
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- один worktree принадлежит одному агенту;
|
||||
- не запускать двух агентов в одном dirty worktree;
|
||||
- не менять и не удалять чужой worktree;
|
||||
- generated caches и proprietary data не переносятся commit/cherry-pick;
|
||||
- перед handoff ветка синхронизируется с актуальным `origin/master`.
|
||||
|
||||
## Разделение задач
|
||||
|
||||
Хороший work package:
|
||||
|
||||
- даёт один наблюдаемый результат;
|
||||
- принадлежит преимущественно одной подсистеме;
|
||||
- имеет явные входы/выходы;
|
||||
- меняет не более одного публичного contract одновременно;
|
||||
- имеет собственные tests/diagnostics;
|
||||
- может быть review и merged независимо либо после одной явно указанной dependency.
|
||||
|
||||
Плохое разделение:
|
||||
|
||||
- «сделать сеть»;
|
||||
- один агент меняет protocol и UI напрямую;
|
||||
- два агента одновременно рефакторят один monolithic file;
|
||||
- задача зависит от незаписанного устного соглашения;
|
||||
- work package оставляет временный второй источник истины.
|
||||
|
||||
## Parallelization patterns
|
||||
|
||||
### Contract first
|
||||
|
||||
Для cross-layer feature сначала отдельным маленьким work package фиксируются:
|
||||
|
||||
- domain types;
|
||||
- commands/events/read models;
|
||||
- version/capabilities;
|
||||
- failure states;
|
||||
- contract tests.
|
||||
|
||||
После merge независимо работают producer и consumers.
|
||||
|
||||
Пример:
|
||||
|
||||
```text
|
||||
WP-A: MovementSnapshot contract
|
||||
├─ WP-B: network movement decoder
|
||||
├─ WP-C: gameplay reconciliation
|
||||
└─ WP-D: character/camera presentation
|
||||
```
|
||||
|
||||
### Fixtures in parallel
|
||||
|
||||
Пока один агент реализует pure logic, второй может готовить:
|
||||
|
||||
- synthetic fixtures;
|
||||
- original-client comparison procedure;
|
||||
- server-core matrix;
|
||||
- visual checkpoints;
|
||||
- documentation/reference analysis.
|
||||
|
||||
Fixture agent не изменяет production contract без согласования.
|
||||
|
||||
### Adapter split
|
||||
|
||||
После merge canonical interface допустимо параллельно реализовать TrinityCore и AzerothCore adapters, если у каждого разные файлы и общая contract suite.
|
||||
|
||||
### Hotspot extraction first
|
||||
|
||||
Если работа требует одного большого файла, сначала один владелец извлекает стабильный seam. Параллельная работа начинается только после merge seam, а не внутри разных участков монолита.
|
||||
|
||||
## Hotspot-файлы
|
||||
|
||||
Следующие пути требуют явного указания в claim и согласования с интегратором:
|
||||
|
||||
- `project.godot`;
|
||||
- `AGENTS.md`, `docs/README.md`, `targets/README.md`;
|
||||
- текущий `targets/[0-9][0-9]-*.md`;
|
||||
- `RENDER.md`;
|
||||
- `src/scenes/streaming/streaming_world_loader.gd` до декомпозиции;
|
||||
- native registration/CMake/GDExtension manifests;
|
||||
- editor `plugin.cfg` и root plugin lifecycle;
|
||||
- shared schema/version/format constants;
|
||||
- dependency lockfiles и submodules.
|
||||
|
||||
Два активных work packages не должны редактировать один hotspot. При необходимости интегратор выделяет serial integration window.
|
||||
|
||||
## Изменение contracts и форматов
|
||||
|
||||
Contract/schema change обязан иметь:
|
||||
|
||||
- owner и потребителей;
|
||||
- backward compatibility или migration;
|
||||
- old/new fixtures;
|
||||
- version bump policy;
|
||||
- rollout order;
|
||||
- ADR для существенного решения.
|
||||
|
||||
Merge order:
|
||||
|
||||
1. contract + compatibility layer;
|
||||
2. producers;
|
||||
3. consumers;
|
||||
4. removal deprecated path отдельным work package.
|
||||
|
||||
Нельзя одновременно удалить старый API и ожидать, что незамердженная ветка другого агента уже использует новый.
|
||||
|
||||
## Commits
|
||||
|
||||
Формат заголовка:
|
||||
|
||||
```text
|
||||
<program>(<target>): <imperative summary>
|
||||
```
|
||||
|
||||
Примеры:
|
||||
|
||||
```text
|
||||
fnd(M01): add canonical coordinate mapper
|
||||
net(M08): decode auth challenge safely
|
||||
rnd(M03): extract streaming target planner
|
||||
test(M00): add paired checkpoint manifest
|
||||
```
|
||||
|
||||
Описание commit/PR содержит:
|
||||
|
||||
```text
|
||||
Work-Package: M01-FND-COORDS-001
|
||||
Agent: sindo-main-codex
|
||||
Tests: <commands/results>
|
||||
Fidelity: <evidence/gap>
|
||||
```
|
||||
|
||||
Не смешивать formatting unrelated files, generated artifacts и функциональное изменение в одном commit.
|
||||
|
||||
## Handoff protocol
|
||||
|
||||
Готовый work package получает marker:
|
||||
|
||||
```text
|
||||
<!-- OPENWC_HANDOFF:READY:M01-FND-COORDS-001:<commit> -->
|
||||
```
|
||||
|
||||
Handoff обязан содержать:
|
||||
|
||||
- точный commit/branch;
|
||||
- outcome и изменённые paths;
|
||||
- публичные contracts/schema changes;
|
||||
- verification commands и результаты;
|
||||
- fidelity evidence/known gaps;
|
||||
- migration/cache/rebuild requirements;
|
||||
- unresolved risks;
|
||||
- recommended merge order;
|
||||
- updated API/module documentation и перечень diagrams.
|
||||
|
||||
Если работа частичная:
|
||||
|
||||
```text
|
||||
<!-- OPENWC_HANDOFF:PARTIAL:M01-FND-COORDS-001:<commit> -->
|
||||
```
|
||||
|
||||
`PARTIAL` не считается завершением и не разрешает ставить target `DONE`.
|
||||
|
||||
## Integration protocol
|
||||
|
||||
Интегратор:
|
||||
|
||||
1. Проверяет claim и отсутствие overlapping ownership.
|
||||
2. Проверяет diff на unrelated/user changes.
|
||||
3. Синхронизирует branch с `master` без уничтожения чужой истории.
|
||||
4. Запускает package verification и затронутые общие gates.
|
||||
5. Проверяет docs, migrations, cache versions и fidelity statement.
|
||||
6. Проверяет documentation gate из `docs/DOCUMENTATION_STANDARD.md`: API docs, inputs/outputs, diagrams, ownership и recovery.
|
||||
7. Merge/squash выполняет в соответствии с историей work package.
|
||||
8. После merge запускает post-merge smoke.
|
||||
9. Закрывает claim marker-ом:
|
||||
|
||||
```text
|
||||
<!-- OPENWC_INTEGRATION:ACCEPTED:M01-FND-COORDS-001:<merge-commit> -->
|
||||
```
|
||||
|
||||
Только после интеграции всех обязательных work packages интегратор обновляет target Evidence/status.
|
||||
|
||||
## Конфликты
|
||||
|
||||
При обнаружении overlapping edits агент должен остановить изменение затронутого файла и связаться с владельцем. Запрещено:
|
||||
|
||||
- разрешать конфликт через слепое `ours/theirs`;
|
||||
- копировать чужой файл поверх своего;
|
||||
- делать `reset --hard` или checkout чужих изменений;
|
||||
- «временно» дублировать contract без migration plan.
|
||||
|
||||
Порядок разрешения:
|
||||
|
||||
1. определить semantic owner;
|
||||
2. выбрать merge order;
|
||||
3. первый владелец публикует минимальный contract/seam;
|
||||
4. второй rebase и адаптирует свою ветку;
|
||||
5. integration tests подтверждают совместимость.
|
||||
|
||||
## Status updates и stale work
|
||||
|
||||
Владелец обновляет claim после значимого результата или не реже срока lease. Status краткий:
|
||||
|
||||
```text
|
||||
State: active | waiting | ready | partial
|
||||
Done: ...
|
||||
Next: ...
|
||||
Blocked by: ...
|
||||
Touched paths: ...
|
||||
```
|
||||
|
||||
Если работа прекращена, claim явно освобождается. Незавершённую ветку не удаляют до handoff с описанием пригодных commits и известных проблем.
|
||||
|
||||
## Минимальная схема для двух разработчиков
|
||||
|
||||
- Один человек назначается интегратором текущего milestone.
|
||||
- Второй берёт work package без пересечения файлов либо готовит fixtures/reference/adapter.
|
||||
- Роль интегратора можно менять после каждого milestone.
|
||||
- Перед началом дня оба выполняют `git fetch` и сверяют claims/draft PRs.
|
||||
- Перед merge второй агент не начинает работу поверх непроверенного commit, если dependency не опубликована как contract branch.
|
||||
|
||||
Пример для M01:
|
||||
|
||||
```text
|
||||
Developer A / integrator:
|
||||
M01-FND-COORDS-001 — coordinate types and mapper
|
||||
|
||||
Developer B:
|
||||
M01-QAR-COORD-FIXTURES-001 — known ADT/server points and tests
|
||||
|
||||
После merge contract:
|
||||
A — StreamingFocus migration
|
||||
B — placement/SQL conversion audit
|
||||
```
|
||||
|
||||
## Автоматическая проверка
|
||||
|
||||
Перед handoff и merge запускать:
|
||||
|
||||
```powershell
|
||||
.\tools\verify_coordination.ps1
|
||||
.\tools\verify_documentation.ps1
|
||||
```
|
||||
|
||||
Первая проверка требует ровно один `ACTIVE` numbered target, соответствие `Current target`, валидные и уникальные fallback claim markers. Вторая проверяет обязательные documentation files, структуру module specs, наличие data-flow diagram и относительные ссылки. Истёкший claim выдаёт warning и требует человеческого решения, но не удаляется автоматически.
|
||||
Reference in New Issue
Block a user