feat: добавить документацию Template Sync Strategy
- добавлены каноны и VitePress-сайт стратегии обновления шаблонов - подключена карточка документации на главной странице - добавлены сборочные скрипты, Caddy-маршрут и Docker-сборка - добавлена git-иконка для карточки и сгенерированы публичные артефакты
This commit is contained in:
119
canons/template-sync-strategy/setup/clean-repository.md
Normal file
119
canons/template-sync-strategy/setup/clean-repository.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: Новый проект от шаблона
|
||||
description: Старт нового приложения от шаблонного репозитория с правильной историей веток.
|
||||
---
|
||||
|
||||
# Новый проект от шаблона
|
||||
|
||||
Этот сценарий подходит, когда репозиторий приложения ещё пустой или его можно безопасно пересоздать от шаблона.
|
||||
|
||||
Целевая модель:
|
||||
|
||||
```text
|
||||
templates/master -> template -> sync/* -> master
|
||||
```
|
||||
|
||||
## Условия
|
||||
|
||||
Есть два репозитория:
|
||||
|
||||
```text
|
||||
template repo = репозиторий шаблона
|
||||
app repo = репозиторий приложения
|
||||
```
|
||||
|
||||
В обоих репозиториях основная ветка называется `master`.
|
||||
|
||||
## Подготовить шаблон
|
||||
|
||||
В репозитории шаблона:
|
||||
|
||||
```bash
|
||||
cd /path/to/template-repo
|
||||
git switch master
|
||||
```
|
||||
|
||||
Если это пустой репозиторий, добавьте первый файл и запушьте `master`:
|
||||
|
||||
```bash
|
||||
printf "# Template Repository\n\nBase template version: v1\n" > README.md
|
||||
git add README.md
|
||||
git commit -m "docs: добавить базовый шаблон"
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
## Подключить шаблон в приложении
|
||||
|
||||
В репозитории приложения:
|
||||
|
||||
```bash
|
||||
cd /path/to/app-repo
|
||||
git remote add templates <template-repo-url>
|
||||
git fetch templates
|
||||
```
|
||||
|
||||
Создайте ветку `template` от шаблона:
|
||||
|
||||
```bash
|
||||
git switch -c template templates/master
|
||||
git push -u origin template
|
||||
```
|
||||
|
||||
Создайте ветку приложения `master` от `template`:
|
||||
|
||||
```bash
|
||||
git switch -c master template
|
||||
```
|
||||
|
||||
Добавьте слой приложения:
|
||||
|
||||
```bash
|
||||
mkdir -p app
|
||||
printf "Application code v1\n" > app/app.txt
|
||||
git add app/app.txt
|
||||
git commit -m "feat: добавить слой приложения"
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
После этого история выглядит так:
|
||||
|
||||
```text
|
||||
template: T1
|
||||
master: T1---A1
|
||||
```
|
||||
|
||||
Где `T1` — коммит шаблона, а `A1` — коммит приложения.
|
||||
|
||||
## Настроить pull и push для template
|
||||
|
||||
Можно сделать так, чтобы на ветке `template`:
|
||||
|
||||
```text
|
||||
git pull тянул из templates/master
|
||||
git push пушил в origin/template
|
||||
```
|
||||
|
||||
Команды:
|
||||
|
||||
```bash
|
||||
git config branch.template.remote templates
|
||||
git config branch.template.merge refs/heads/master
|
||||
git config branch.template.pushRemote origin
|
||||
```
|
||||
|
||||
Дополнительно можно запретить случайный push в репозиторий шаблона:
|
||||
|
||||
```bash
|
||||
git remote set-url --push templates DISABLED
|
||||
```
|
||||
|
||||
## Дальше
|
||||
|
||||
После первичной настройки постоянные ветки такие:
|
||||
|
||||
```text
|
||||
template = чистый шаблон
|
||||
master = приложение
|
||||
```
|
||||
|
||||
Обновления шаблона выполняются через временные ветки `sync/*` по инструкции [Обычное обновление шаблона](../workflows/update-template.md).
|
||||
144
canons/template-sync-strategy/setup/existing-master-migration.md
Normal file
144
canons/template-sync-strategy/setup/existing-master-migration.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
title: Миграция существующего master
|
||||
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).
|
||||
Reference in New Issue
Block a user