# Git-ветки и коммиты Flexly CMS ## Именование Для новой функциональности и изменений по спецификации используем: ```text /spec-- ``` Примеры для существующих спецификаций: ```text feat/spec-001-content-publication fix/spec-001-publication-navigation feat/spec-002-theme-manager fix/spec-003-editor-update-queue docs/spec-001-runtime ``` `spec-001`, `spec-002`, `spec-003` соответствуют каталогам в `specs/`: `001-antirion-admin`, `002-site-studio-theme`, `003-background-editor`. Несколько этапов одной спецификации могут иметь отдельные ветки с разными slug. Номер новой спецификации выбирается по каталогу `specs/`, а не по числу веток. Для небольшой работы без спецификации достаточно `/`, например `docs/mcp-agent-integration` или `chore/test-runner`. В проекте нет обязательного трекерного префикса; чужие идентификаторы `po-N` не используются. `slug` — короткое описание строчными ASCII-буквами в kebab-case. Не добавляем даты, имя автора и служебные суффиксы. Рекомендуемая длина имени — до 80 символов. Если инструмент создаёт ветку автоматически, передаём имя в этом формате. Существующие ветки ради нового правила не переименовываем. ## Типы | Тип | Назначение | |---|---| | `feat` | Новая возможность или этап спецификации | | `fix` | Исправление дефекта или регрессии | | `docs` | Только документация, спецификации и архитектурные предложения | | `chore` | Зависимости, инструменты, CI и техническое обслуживание | | `hotfix` | Срочное исправление работающего развёртывания | Тип выбираем по цели. Тесты, необходимые для новой возможности или исправления, входят в ту же ветку; отдельные типы `test`, `refactor`, `ci`, `perf` не нужны. ## База и жизненный цикл - Основная ветка проекта — `main`. Отдельная интеграционная `dev` сейчас не используется. - Новые рабочие ветки создаём от актуальной локальной `main`; получение изменений с remote выполняем, когда он настроен и доступен. Не подразумеваем наличие branch protection, автоматического CI или обязательной платформы для PR. - Для следующей самостоятельной работы предпочитаем рабочую ветку. Текущие изменения, уже подготовленные в `main`, можно завершить там по согласованной команде пользователя на коммит; перенос ради самого имени ветки не требуется. - Перед объединением проверяем diff, запускаем проверки по изменению и описываем результат. Для интерфейса проверяем настоящий FastAPI в браузере, включая переходы через htmx, широкое и мобильное окно. Для runtime/API выполняем соответствующие серверные тесты; перед выпуском — полную регрессию и wheel. Команды и ограничения — [AGENTS.md](../AGENTS.md) и отчёты в `specs/`. - Каждый согласованный этап переноса дизайна проверяет пользователь, как указано в [AGENTS.md](../AGENTS.md). Успешная автоматическая проверка не заменяет эту приёмку. - Способ объединения выбираем по задаче, сохраняя понятную историю. Не переписываем опубликованную историю и не делаем force-push без отдельного согласования. - Push, публикация PR и развёртывание — отдельные действия. Разрешение на локальный коммит само по себе не означает разрешение на выпуск на сервер. - После объединения рабочую ветку можно удалить, если она больше не нужна; удаление ветки на remote согласуем отдельно. ## Состав коммитов Коммит должен содержать законченное изменение: исходники, необходимые шаблоны и статику, тесты, актуальный контракт и документацию. Общие изменения одного runtime не разделяем так, чтобы промежуточный коммит переставал работать. Независимые архитектурные документы и инструменты можно коммитить отдельно. Заголовок начинаем с действия и указываем результат; допустим формат `feat(admin): add publication candidates` или привычный проекту `Add publication candidates`. При добавлении ресурсов админки проверяем их включение в wheel, происхождение дизайна в `static/VENDOR.md` и отсутствие изменений сгенерированного контракта без соответствующего API. `design/`, `examples/site-studio/`, исходники builtin и `AGENTS.md` — версионируемые части проекта; состав конкретного коммита зависит от задачи. Не добавляем секреты и рабочие артефакты: `.env`, `data/`, `.engine/`, служебное состояние, `dist/`, `build/`, журналы и браузерные снимки из `/tmp`. Перед коммитом проверяем `git diff --cached` и `git diff --check`.