Document CMS branching and external agent integration
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user