Files
flexly-cms/docs/BRANCHING.md
T

89 lines
6.9 KiB
Markdown

# Git-ветки и коммиты Flexly CMS
## Именование
Для новой функциональности и изменений по спецификации используем:
```text
<type>/spec-<NNN>-<slug>
```
Примеры для существующих спецификаций:
```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/`, а не по числу веток.
Для небольшой работы без спецификации достаточно `<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](../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`.