Источник истины

Источник истины#

Этот документ фиксирует иерархию источников истины, чтобы green-robot, продуктовые репозитории и их README.md не расходились по смыслу.

1. Уровни истины#

1.1. Published canonical#

Published canonical живет в green-robot и используется для:

  • пользовательской документации;

  • регистрации и нормативного пакета;

  • каталога продуктов и приборов;

  • общей платформенной архитектуры;

  • описания отраслевых применений.

Эти документы считаются внешне согласованной версией и не должны зависеть от знания внутренней структуры кода отдельных репозиториев.

1.2. Engineering canonical#

Engineering canonical живет в инженерных репозиториях и используется для:

  • реализации продукта;

  • локальной архитектуры;

  • build/run/test/deploy деталей;

  • внутренних API/firmware/hardware нюансов;

  • developer и operator workflows конкретного продукта.

Такие документы могут быть глубже и быстрее меняться, чем published-слой.

1.3. Agent-facing canonical#

README.md в корне каждого репозитория — обязательный agent-facing source-of-truth.

Его задача:

  • быстро объяснить, за что отвечает репозиторий;

  • указать соответствующий продукт и published-карточку в green-robot;

  • указать локальные engineering source-of-truth разделы;

  • задать правила синхронизации документации.

README.md не входит в Jupyter Book, но обязателен для согласованной работы агентов и разработчиков.

2. Приоритет при конфликте#

  1. Для пользовательского, регистрационного, продуктового и платформенного описания приоритет у green-robot.

  2. Для локальной реализации и инженерных деталей приоритет у product/hardware repo.

  3. Если конфликт затрагивает общие контракты или границы продуктов, сначала обновляется green-robot, затем локальные repo.

  4. Если конфликт затрагивает только локальную реализацию без изменения published-смысла, обновляется инженерный repo; green-robot меняется только при необходимости публикации нового смысла.

  5. Если меняется связка iP-1220 -> green-robot-go -> iP-1510, включая published contract project/monitoring/ws, auth/access, локальный интерфейс L1, верхний уровень L2 или update/deploy contour, published docs green-robot и инженерные docs должны синхронизироваться в том же push/PR.

Дополнение по инженерным семействам:

  • iC-4, iO-5, iU-6 закреплены как engineering-семейства за ../ioot-pro-hardware;

  • iD-7 рассматривается как отдельный контур механики и электрики и должен иметь собственный engineering repo.

3. Что нельзя делать локально#

В продуктовых репозиториях нельзя молча переопределять:

  • общую архитектурную модель платформы;

  • продуктовые идентификаторы и классификацию;

  • общие API/event/security conventions;

  • published-состав коробочного отраслевого решения.

Такие изменения должны проходить через green-robot.

4. Минимальный набор ссылок в каждом README#

Каждый корневой README.md должен содержать:

  • продукт или контур, за который отвечает repo;

  • published canonical карточку в green-robot;

  • локальный engineering source-of-truth;

  • правила синхронизации;

  • границы ответственности команды/repo.

Содержание