Files

Michael Chus 1977730d93 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>

2026-06-12 10:17:50 +03:00

2.5 KiB

Raw Permalink Blame History

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:

Производить, нормализовывать и сериализовывать новые данные в самом host-проекте.
Обновить JSON-контракт (например, bible-local/docs/hardware-ingest-contract.md), чтобы viewer мог читать их из стандартного snapshot.
Предложить поддержку нового поля в upstream viewer как generic-изменение.

Почему

Конкретный провал: попытка добавить telemetry storage в bee через редактирование internal/chart/ создала coupling shared viewer с одним host-проектом и риск скрытых регрессий в других проектах, использующих тот же chart.

Документирование интеграции

В bible-local/ host-проекта должен быть явный контракт:

Какие данные ожидает submodule на входе.
Как host-проект их производит (какой модуль/файл).
Текущий upstream commit/tag submodule.

2.5 KiB Raw Permalink Blame History Unescape Escape