Перейти к содержанию

ADR 0001: Git — предварительное требование; механика Git собрана в одном месте

  • Статус: Accepted
  • Дата: 2026-10-07
  • Владельцы: мейнтейнеры EmbrAIon
  • Заменяет: нет
  • Заменена: нет

Контекст

Issue #86 спрашивал, какие правила Git в workflow Core универсальны. Workflow worktree называл общий каталог Git, локальные и удалённые ссылки, удаление удалённой ветки, доказательство интеграции через squash и создание удалённой ветки командой worktree publish. Workflow delivery называл HEAD источника pull request, подтверждение base и diff и заметку о SHA squash-коммита. Вопрос был в том, нужно ли скрыть это за нейтральным слоем систем контроля версий.

Наблюдаемые факты:

  • EmbrAIon живёт на GitHub и поставляется с доставкой через GitHub.
  • CLI уже вызывает git напрямую для worktree, проверок, записей решений и проверок организации. gh вызывается только для данных GitHub в embraion worktree gc.
  • В репозитории нет поддержки другой системы контроля версий.

Владелец решил 2026-10-07, что EmbrAIon может и должен знать Git, и что Git фактически обязателен.

Решение

  • Git — заявленное предварительное требование EmbrAIon. GitHub — поддерживаемая платформа хостинга и доставки.
  • Требование описано один раз, в требованиях к установке. Остальные страницы ссылаются на него.
  • Универсальные примитивы остаются в формулировках Core: изолированное рабочее пространство, идентичность проверенного изменения и доказательство интеграции. Каждое правило безопасности сохраняет смысл: очистка с отказом при неопределённости, доказательство интеграции по точному HEAD, аннулирование проверки после любого изменения кандидата и подтверждение HEAD источника перед слиянием.
  • Механика Git и GitHub собрана на одной странице, core/workflows/git.md. Workflow worktree и delivery ссылаются на неё.
  • Core остаётся независимым от конкретного AI-хоста и провайдера моделей. Выбор GitHub поддерживаемой платформой доставки — осознанное ограниченное исключение: оно касается workflow delivery и worktree и страницы с их механикой и ничего больше в Core.
  • Абстрактный слой систем контроля версий не создаётся.

Последствия

Что переезжает: область общего каталога Git, условия удаления ссылок, механика lease в worktree publish, список доказательств влитого pull request и заметка о SHA squash-коммита переходят из worktree.md и delivery.md в git.md. В workflow остаётся по одному короткому предложению с ссылкой на нужный раздел.

Что не переезжает: worktree.md сохраняет одно общее предложение о том, что требования конкретного репозитория, например загрузка Git LFS, остаются конфигурацией проекта или инструмента. Это решение не меняет поведение команд.

Цена: читателю workflow нужно перейти по одной ссылке, чтобы увидеть детали Git. Каталог Core не перечисляет git.md: это справочник, доступный из двух workflow каталога, а не отдельная возможность.

Рассмотренные альтернативы

  • Абстрактный слой систем контроля версий, где Git — один из адаптеров. Отклонено. Второй системы нет и не планируется, поэтому слой был бы умозрительным. Он добавил бы словарь и косвенность к правилам, безопасность которых зависит от точных фактов Git: SHA, lease, общий каталог. Он также скрыл бы требование Git, которое пользователи должны выполнить.
  • Оставить механику внутри двух workflow. Отклонено. Универсальные правила остаются трудными для чтения, а один факт размазан по нескольким местам.
  • Поместить механику в папку адаптеров. Отклонено. Переносимый пакет содержит workflow Core, но не файлы адаптеров, поэтому ссылка из Core в адаптер там сломалась бы.

Проверка и свидетельства

  • python tools/source.py validate и наборы unit- и integration-тестов проверяют схемы, паритет документации, ссылки, пути каталога и проекции.
  • Результаты тестов записаны в pull request, который несёт это решение, а не здесь.

Внедрение и совместимость

  • Это решение не меняет поведение команд. Оно переносит формулировки между файлами workflow Core, сохраняет их пути и существующие id и пути каталога и привязывает слот знаний decisions этого репозитория к docs/architecture/decisions.
  • Оно не вводит новых сохраняемых форматов. Другие изменения в pull request, который его несёт, имеют собственные заметки о совместимости.
  • Откат: отмените перенос формулировок. Миграция не нужна.
  • Любое изменение поведения embraion worktree требует отдельной проверки совместимости.