refactor: перенести сборку в проекты
All checks were successful
CI/CD Pipeline / build (push) Successful in 39s
CI/CD Pipeline / docker (push) Successful in 1m30s
CI/CD Pipeline / deploy (push) Successful in 8s

- перенесены каноны и VitePress-конфиги в projects/<slug>

- добавлены корневой и проектные build.ts для сборки артефактов

- добавлены shared-библиотеки сборки в projects/_shared/lib

- обновлены CI, Dockerfile, package.json, gitignore и README

- удалена сборка frontend-агента
This commit is contained in:
2026-05-22 19:07:10 +03:00
parent a53c5fc1b1
commit bdb99ade62
117 changed files with 442 additions and 568 deletions

View File

@@ -0,0 +1,72 @@
---
title: Модель веток
description: Роли веток и remote в стратегии обновления проекта от шаблона.
---
# Модель веток
Целевая схема:
```text
templates/master -> template -> sync/* -> master
```
Это логическая модель ответственности. Она не требует физически разделять файлы шаблона и приложения по папкам.
## templates/master
`templates/master` — это `master` из репозитория шаблона.
В репозитории приложения он доступен через remote `templates`:
```bash
git remote add templates <template-repo-url>
git fetch templates
```
Этот remote считается источником обновлений шаблона.
## template
`template` — чистый слепок шаблона внутри репозитория приложения.
Его задача — показать, какая версия шаблонной базы сейчас доступна приложению.
В `template` нельзя коммитить руками изменения приложения. Эта ветка обновляется только из `templates/master`.
## master
`master` — основная ветка приложения.
Она содержит:
- базу шаблона;
- продуктовый код;
- локальные настройки приложения;
- историю применения обновлений шаблона.
`master` не используется как место ручного решения конфликтов при обновлении шаблона.
## sync/*
`sync/*` — временная ветка для обновления приложения от шаблона.
Она создаётся от актуального `origin/master`, после чего в неё вливается `origin/template`.
Пример:
```bash
git fetch origin
git switch -c sync/update-template-v2 origin/master
git merge origin/template
```
Если появляются конфликты, они решаются именно в этой ветке.
## Почему нужен отдельный sync-слой
Нельзя безопасно использовать `template` как source branch для прямого PR/MR в `master`: если возникнет конфликт, решение может попасть в `template`.
После этого `template` перестанет быть чистым слепком шаблона. Git начнёт видеть в ней не только шаблон, но и локальные решения конкретного приложения.
`sync/*` можно пачкать conflict resolve-коммитами, проверками и правками совместимости. Эта ветка временная и удаляется после merge.

View File

@@ -0,0 +1,47 @@
---
title: Правила процесса
description: Набор правил, который удерживает template чистой, а обновления шаблона контролируемыми.
---
# Правила процесса
Небольшой набор правил удерживает схему чистой.
## Делаем
- `template` обновляем только из `templates/master`.
- `sync/*` создаём от `origin/master`.
- `origin/template` вливаем в `sync/*`, а не напрямую в `master`.
- Конфликты решаем только в `sync/*`.
- `sync/* -> master` вливаем через PR/MR.
- Для sync-PR/MR отключаем squash.
## Не делаем
- Не правим `template` руками.
- Не коммитим изменения приложения в `template`.
- Не мержим `template -> master` напрямую.
- Не решаем конфликты в `master`.
- Не включаем squash для `sync/* -> master`.
## Почему squash нельзя
Squash может уничтожить нормальную связь истории `master` с историей `template`.
Git использует историю, чтобы понимать, какие изменения шаблона уже были доставлены в приложение. Если результат обновления шаблона превратить в один squash-коммит, связь с исходными коммитами шаблона станет хуже или исчезнет.
Для sync-PR/MR допустимы:
```text
fast-forward merge = хорошо
merge commit = допустимо
squash merge = нельзя
```
## Почему template нельзя пачкать
`template` — эталонный слепок оригинального шаблона.
Если в неё попадает локальное решение конфликта или изменение приложения, она перестаёт отвечать на вопрос: “какая версия шаблона сейчас подключена к приложению?”.
После этого ломается главная граница ответственности: шаблон отдельно, приложение отдельно, конфликтная зона отдельно.

View File

@@ -0,0 +1,44 @@
---
title: Зачем это нужно
description: Почему шаблону нужен процесс обновления, а не только быстрый старт нового проекта.
---
# Зачем это нужно
Шаблон закрывает повторяющуюся техническую базу проекта: CI/CD, Dockerfile, зависимости, lint, build, структуру каталогов и базовую документацию.
Это снимает рутину на старте. Команде не нужно каждый раз заново собирать одинаковый технический каркас.
## Проблема после старта
Создать проект легко. Поддерживать 10-20 проектов сложнее.
Сначала проекты похожи. Потом они начинают расходиться:
- В одном проекте обновили CI, в другом забыли.
- В одном проекте Dockerfile остался из шаблона, в другом его локально поправили.
- В одном проекте зависимости уже свежие, в другом остались старые версии.
- В одном проекте изменения шаблона перенесли руками, в другом потеряли.
Без процесса обновления шаблон перестаёт быть общей основой. Он остаётся только способом быстро создать первый коммит.
## Что ломается без стратегии
Когда шаблон нельзя нормально обновлять:
- проекты начинают жить своей жизнью;
- граница между шаблоном и приложением теряется;
- обновления превращаются в ручное копирование;
- конфликты решаются прямо в рабочих ветках;
- становится непонятно, какой проект на какой версии шаблона;
- Git-история перестаёт быть источником правды.
Это особенно больно, когда приложений много. Для одного проекта ручной перенос ещё можно пережить. Для набора проектов нужен единый маршрут обновления.
## Цель стратегии
Стратегия не пытается убрать конфликты полностью. Она делает так, чтобы конфликты возникали в предсказуемом месте, проходили review и не ломали чистую ветку шаблона.
Главная формулировка:
> Шаблон должен обновляться так же контролируемо, как обычная фича: через ветку, проверку и PR/MR.