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.