Add hardware-ingest-json and submodule-integration contracts; expand go-database cursor safety
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>
This commit is contained in:
41
rules/patterns/submodule-integration/contract.md
Normal file
41
rules/patterns/submodule-integration/contract.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user