89 lines
6.9 KiB
Markdown
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`.
|