Files

6.9 KiB

Git-ветки и коммиты Flexly CMS

Именование

Для новой функциональности и изменений по спецификации используем:

<type>/spec-<NNN>-<slug>

Примеры для существующих спецификаций:

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/, а не по числу веток.

Для небольшой работы без спецификации достаточно <type>/<slug>, например 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 и отчёты в specs/.
  • Каждый согласованный этап переноса дизайна проверяет пользователь, как указано в 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.