Michael Chus
1977730d93
Synthesized from bible-local reviews across bee, logpile, core, chart, PriceForge: - rules/patterns/hardware-ingest-json/contract.md — Reanimator JSON ingest schema v2.10 - rules/patterns/submodule-integration/contract.md — read-only submodule principle - go-database: add driver-level violation symptoms for cursor safety rule Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# Contract: Git Submodule Integration
|
||
|
||
Version: 1.0
|
||
|
||
Правила для проектов, использующих git submodules (shared libraries, viewers, bible, tooling).
|
||
|
||
Применяется в: `bee` (internal/chart/, bible/), `chart`, `logpile/internal/chart/`, `PriceForge`.
|
||
|
||
## Основное правило
|
||
|
||
**Embedded submodules — read-only с точки зрения host-проекта.**
|
||
|
||
## Запрещено
|
||
|
||
- Реализовывать project-specific поведение путём редактирования кода submodule.
|
||
- Вносить в submodule изменения, специфичные для одного host-проекта.
|
||
- Держать в submodule локальные неотправленные коммиты как часть feature host-проекта.
|
||
|
||
## Разрешено
|
||
|
||
- Обновлять указатель submodule на upstream-коммит после merge там.
|
||
- Если нужна новая возможность в submodule — предложить и влить её в upstream как generic-изменение, затем подтянуть через обновление указателя.
|
||
|
||
## Когда нужны новые данные
|
||
|
||
Если host-проект нуждается в новых данных, которые должен отображать submodule-viewer:
|
||
|
||
1. Производить, нормализовывать и сериализовывать новые данные в самом host-проекте.
|
||
2. Обновить JSON-контракт (например, `bible-local/docs/hardware-ingest-contract.md`), чтобы viewer мог читать их из стандартного snapshot.
|
||
3. Предложить поддержку нового поля в upstream viewer как generic-изменение.
|
||
|
||
## Почему
|
||
|
||
Конкретный провал: попытка добавить telemetry storage в `bee` через редактирование `internal/chart/` создала coupling shared viewer с одним host-проектом и риск скрытых регрессий в других проектах, использующих тот же `chart`.
|
||
|
||
## Документирование интеграции
|
||
|
||
В `bible-local/` host-проекта должен быть явный контракт:
|
||
- Какие данные ожидает submodule на входе.
|
||
- Как host-проект их производит (какой модуль/файл).
|
||
- Текущий upstream commit/tag submodule.
|