feat: добавить документацию Template Sync Strategy
- добавлены каноны и VitePress-сайт стратегии обновления шаблонов - подключена карточка документации на главной странице - добавлены сборочные скрипты, Caddy-маршрут и Docker-сборка - добавлена git-иконка для карточки и сгенерированы публичные артефакты
This commit is contained in:
29
public/template-sync-strategy/concepts/model.html
Normal file
29
public/template-sync-strategy/concepts/model.html
Normal file
File diff suppressed because one or more lines are too long
72
public/template-sync-strategy/concepts/model.md
Normal file
72
public/template-sync-strategy/concepts/model.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
url: /template-sync-strategy/concepts/model.md
|
||||
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.
|
||||
28
public/template-sync-strategy/concepts/rules.html
Normal file
28
public/template-sync-strategy/concepts/rules.html
Normal file
File diff suppressed because one or more lines are too long
49
public/template-sync-strategy/concepts/rules.md
Normal file
49
public/template-sync-strategy/concepts/rules.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
url: /template-sync-strategy/concepts/rules.md
|
||||
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` — эталонный слепок оригинального шаблона.
|
||||
|
||||
Если в неё попадает локальное решение конфликта или изменение приложения, она перестаёт отвечать на вопрос: “какая версия шаблона сейчас подключена к приложению?”.
|
||||
|
||||
После этого ломается главная граница ответственности: шаблон отдельно, приложение отдельно, конфликтная зона отдельно.
|
||||
26
public/template-sync-strategy/concepts/why.html
Normal file
26
public/template-sync-strategy/concepts/why.html
Normal file
File diff suppressed because one or more lines are too long
46
public/template-sync-strategy/concepts/why.md
Normal file
46
public/template-sync-strategy/concepts/why.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
url: /template-sync-strategy/concepts/why.md
|
||||
description: >-
|
||||
Почему шаблону нужен процесс обновления, а не только быстрый старт нового
|
||||
проекта.
|
||||
---
|
||||
|
||||
# Зачем это нужно
|
||||
|
||||
Шаблон закрывает повторяющуюся техническую базу проекта: CI/CD, Dockerfile, зависимости, lint, build, структуру каталогов и базовую документацию.
|
||||
|
||||
Это снимает рутину на старте. Команде не нужно каждый раз заново собирать одинаковый технический каркас.
|
||||
|
||||
## Проблема после старта
|
||||
|
||||
Создать проект легко. Поддерживать 10-20 проектов сложнее.
|
||||
|
||||
Сначала проекты похожи. Потом они начинают расходиться:
|
||||
|
||||
* В одном проекте обновили CI, в другом забыли.
|
||||
* В одном проекте Dockerfile остался из шаблона, в другом его локально поправили.
|
||||
* В одном проекте зависимости уже свежие, в другом остались старые версии.
|
||||
* В одном проекте изменения шаблона перенесли руками, в другом потеряли.
|
||||
|
||||
Без процесса обновления шаблон перестаёт быть общей основой. Он остаётся только способом быстро создать первый коммит.
|
||||
|
||||
## Что ломается без стратегии
|
||||
|
||||
Когда шаблон нельзя нормально обновлять:
|
||||
|
||||
* проекты начинают жить своей жизнью;
|
||||
* граница между шаблоном и приложением теряется;
|
||||
* обновления превращаются в ручное копирование;
|
||||
* конфликты решаются прямо в рабочих ветках;
|
||||
* становится непонятно, какой проект на какой версии шаблона;
|
||||
* Git-история перестаёт быть источником правды.
|
||||
|
||||
Это особенно больно, когда приложений много. Для одного проекта ручной перенос ещё можно пережить. Для набора проектов нужен единый маршрут обновления.
|
||||
|
||||
## Цель стратегии
|
||||
|
||||
Стратегия не пытается убрать конфликты полностью. Она делает так, чтобы конфликты возникали в предсказуемом месте, проходили review и не ломали чистую ветку шаблона.
|
||||
|
||||
Главная формулировка:
|
||||
|
||||
> Шаблон должен обновляться так же контролируемо, как обычная фича: через ветку, проверку и PR/MR.
|
||||
Reference in New Issue
Block a user