feat: добавить документацию Template Sync Strategy

- добавлены каноны и VitePress-сайт стратегии обновления шаблонов

- подключена карточка документации на главной странице

- добавлены сборочные скрипты, Caddy-маршрут и Docker-сборка

- добавлена git-иконка для карточки и сгенерированы публичные артефакты
This commit is contained in:
2026-05-13 23:23:31 +03:00
parent 07b349e678
commit 1a14df9366
97 changed files with 3697 additions and 2 deletions

View File

@@ -0,0 +1,146 @@
---
url: /template-sync-strategy/setup/existing-master-migration.md
description: >-
Как одноразово связать master приложения с историей шаблона, если проект был
создан отдельно.
---
# Миграция существующего master
Этот сценарий нужен, если в репозитории приложения уже есть `master`, но он был создан не от шаблона.
## Проблема
Если `master` приложения и `template` имеют разные корневые коммиты, Git видит две несвязанные истории.
Плохое состояние:
```text
template: T1---T2---T3
master: A1---A2
```
При попытке выполнить обычный merge Git может ответить:
```text
fatal: отказ слияния несвязанных историй изменений
```
Это означает, что у веток нет общего предка.
## Цель миграции
Нужно один раз связать истории, чтобы дальше обновления шаблона шли обычным merge-процессом.
После миграции история будет выглядеть примерно так:
```text
template: T1---T2---T3
\
master: A1---A2-----M
```
Где `M` — одноразовый merge-коммит, который связал историю приложения с историей шаблона.
## Подключить репозиторий шаблона
В репозитории приложения:
```bash
cd /path/to/app-repo
git remote add templates <template-repo-url>
git fetch templates
git fetch origin
```
Если remote `templates` уже существует:
```bash
git fetch templates
git fetch origin
```
## Создать или обновить template
Если ветки `template` ещё нет:
```bash
git switch -c template templates/master
git push -u origin template
```
Если ветка `template` уже есть:
```bash
git switch template
git merge --ff-only templates/master
git push origin template
```
Опционально настройте удобное поведение `pull` и `push`:
```bash
git config branch.template.remote templates
git config branch.template.merge refs/heads/master
git config branch.template.pushRemote origin
git remote set-url --push templates DISABLED
```
## Связать master с template
Создайте временную ветку от текущего приложения:
```bash
git fetch origin
git switch -c sync/bootstrap-template origin/master
```
Слейте шаблон с разрешением несвязанных историй:
```bash
git merge --allow-unrelated-histories origin/template
```
Если есть конфликты, решите их в ветке `sync/bootstrap-template`:
```bash
git add .
git commit
```
Если конфликтов не было, Git сам создаст merge-коммит.
Запушьте ветку:
```bash
git push -u origin sync/bootstrap-template
```
Дальше через UI или локально смержите:
```text
sync/bootstrap-template -> master
```
## Что проверить перед merge
Посмотрите граф истории:
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=50
```
Убедитесь, что `sync/bootstrap-template` содержит и историю приложения, и историю шаблона.
Посмотрите итоговый diff:
```bash
git --no-pager diff origin/master...sync/bootstrap-template
```
## Когда миграцию делать не стоит
Не стоит связывать истории, если приложение только что создано и его можно безопасно пересоздать от шаблона.
Для нового проекта лучше сделать чистый старт по инструкции [Новый проект от шаблона](./clean-repository.md).