diff --git a/AGENTS.md b/AGENTS.md index 77f0d95..04cf8db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,7 @@ bin/ docs/ git-workflow/ # Документация, копируемая в проект-потребитель index.md # Оглавление раздела + glossary.md # Словарь терминов со ссылками на определения branches.md # Ветки: типы, именование, жизненный цикл commits.md # Conventional Commits: формат и правила pull-request.md # Процесс PR и требования @@ -50,7 +51,8 @@ docs/ releases/ # Описание артефактов релиза index.md templates/ - release-plan.template.md # Шаблон плана релиза + release-plan.template.md # Шаблон плана обычного релиза + hotfix-release-plan.template.md # Шаблон плана срочного исправления todo/ # Внутренние задачи по доработке пакета ``` diff --git a/README.md b/README.md index 95cb21b..e64ba73 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ ## Правила +- **[Словарь терминов](docs/git-workflow/glossary.md)** — короткие определения со ссылками на отдельные термины - **Ветки** — как назвать ветку для задачи, релиза или хотфикса; когда удалить - **Коммиты** — Conventional Commits: тип, scope, subject — чтобы история читалась как журнал изменений - **Пулреквесты** — от создания до мержа: проверки, ревью, squash diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 3daa0a0..9fd1296 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -15,92 +15,187 @@ package: prikotov/git-workflow ## Целевая модель -- `master` — integration branch для обычной разработки. +- Основная ветка — ветка по умолчанию репозитория и источник обычных релизов; на неё указывает `origin/HEAD`. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. -- `release/x.y` — активная линия стабилизации релиза. +- `release/x.y.z` — отдельная ветка каждого выпуска, включая каждый патч. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки. -- Одновременно поддерживается только одна активная `release/x.y`. +- Одновременно готовь один обычный релиз; срочное исправление может готовиться параллельно. Сохраняй ветки всех выпусков. ## Общие правила -- Запрещены прямые правки в `master`. -- Запрещены прямые правки в `release/*`. +- Вноси изменения в основную ветку только через PR. +- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй его `release/x.y.z` только через PR из `hotfix/*`. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. - Перед стартом убедись, что рабочее дерево чистое: `git status`. - Если есть чужие незакоммиченные изменения — остановись и уточни у пользователя. +- Для синхронизации веток используй только слияние (merge), без переписывания существующих коммитов. +- Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). -## Именование +## Работа с ветками -- `task/` — английский, `kebab-case`, кратко по смыслу. -- `release/x.y` — release line по `major.minor`. -- `hotfix/x.y.z-` — patch version плюс короткое описание. +### Task branch -Примеры: -- `task/docs-release-workflow` -- `release/0.9` -- `hotfix/0.9.3-login-timeout` +Используется для обычной разработки и документации. -## Откуда создавать ветки +#### Именование -### Task branch +`task/` — короткое описание на английском в `kebab-case`. -Используется для обычной разработки и документации. +Пример: `task/docs-release-workflow`. + +#### Создание + +Для обычных задач база и цель PR — основная ветка. Документы будущего релиза можно дополнять в этих же задачах. ```bash -git switch master -git pull origin master +git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. +git remote set-head origin --auto && +# Получить её имя, например origin/main. +base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && +# Убрать префикс origin/ и переключиться на локальную ветку. +git switch "${base#origin/}" && +git pull --ff-only origin "${base#origin/}" && git switch -c task/ ``` +#### Синхронизация + +Синхронизируй `task/*` с основной веткой до окончательного одобрения PR. Находясь в ветке задачи, получи актуальное состояние основной ветки: + +```bash +git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. +git remote set-head origin --auto +``` + +Затем выполни слияние: + +```bash +git merge origin/HEAD +``` + +#### Завершение + +Удали `task/*` локально и в `origin` после слияния PR. + ### Release branch -Создаётся только после решения, что конкретный набор изменений идёт в production. +Используется для подготовки обычного релиза. + +#### Именование + +`release/x.y.z` — полный номер выпуска по `major.minor.patch`. + +Пример: `release/0.9.3`. + +#### Создание + +Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска. + +Для обычного релиза создай ветку от актуальной основной: [процесс релиза](release.md#1-финализация-в-релизной-ветке). + +```bash +git fetch origin && + # Обновить локальный указатель основной ветки по данным origin. + git remote set-head origin --auto && + # Получить её имя, например origin/main. + base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && + # Убрать префикс origin/ и переключиться на локальную ветку. + git switch "${base#origin/}" && + git pull --ff-only origin "${base#origin/}" && + git switch -c release/x.y.z && + git push -u origin release/x.y.z +``` + +Правила для ветки обычного релиза: +- коммить исправления, версии и релизные документы в этой ветке; +- направляй PR из неё в основную ветку; слей PR до публикации тега; +- продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую. + +#### Синхронизация + +Синхронизируй `release/x.y.z` с основной веткой до окончательного одобрения PR. Находясь в релизной ветке, получи актуальное состояние основной ветки: + +```bash +git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. +git remote set-head origin --auto +``` + +Затем выполни слияние: ```bash -git switch master -git pull origin master -git switch -c release/x.y -git push -u origin release/x.y +git merge origin/HEAD ``` -Правила для `release/x.y`: -- в неё попадают только stabilizing changes; -- новые feature PR продолжают идти в `master`; -- после выпуска patch changes из release line не должны теряться в `master`. +#### Завершение + +- Сохраняй `release/x.y.z` и тег выпуска локально и в `origin`. +- Не удаляй релизную ветку при слиянии PR и не переиспользуй для другой версии. +- Отменённого кандидата не тегируй. ### Hotfix branch -По умолчанию hotfix создаётся от **текущего production tag** `vX.Y.Z`, а не от `master`. +Используется для срочного исправления ошибки в рабочей версии без нарушения совместимости. + +#### Именование + +`hotfix/x.y.z-` — версия нового патч-релиза и короткое описание на английском в `kebab-case`. + +Пример: `hotfix/0.9.3-login-timeout`. + +#### Создание + +Для нового выпуска имена веток и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. + +Сначала создай целевую `release/x.y.z` нового выпуска от текущего рабочего тега `vX.Y.Z`. Например: от `v1.2.0` — новую `release/1.2.1`, не меняя `release/1.2.0`. + +```bash +git fetch origin --tags --prune && + git switch -c release/x.y.z vX.Y.Z && + git push -u origin release/x.y.z +``` + +Затем создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`, не от вершины сохранённой релизной ветки. В имени `hotfix/x.y.z-` укажи версию нового выпуска. ```bash -git fetch origin --tags --prune +git fetch origin --tags --prune && git switch -c hotfix/x.y.z- vX.Y.Z ``` -Если активная `release/x.y` уже соответствует текущей production line, hotfix всё равно стартует от production tag, а затем вливается в `release/x.y` и обратно в `master`. +Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). + +#### Синхронизация -## Синхронизация +Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку ни в `hotfix/*`, ни в целевую `release/x.y.z`; изменения в целевую ветку принимай только через PR из `hotfix/*`. -- `task/*` синхронизируется с `master`. -- `release/*` синхронизируется только с собственной release line; новые feature commits из `master` туда не подтягиваются автоматически. -- `hotfix/*` после merge должен присутствовать в active `release/x.y` и в `master`. -- Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. +Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и выполни слияние: ```bash -git fetch origin -git merge origin/master +git fetch origin && +git merge origin/release/x.y.z ``` +#### Возврат в основную ветку + +После публикации GitHub Release открой PR из этой `release/x.y.z` в основную ветку. Если нужна адаптация к основной ветке, выполни её в `release/x.y.z`, не в `hotfix/*`: + ```bash -git fetch origin -git rebase origin/master +git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. +git remote set-head origin --auto && +git switch release/x.y.z && +git merge origin/HEAD ``` -## Завершение +После адаптации повтори проверки и получи одобрение PR. Не меняй опубликованный тег. + +#### Завершение -- После merge PR рабочую ветку нужно удалить локально и в `origin`. -- После выпуска `release/x.y`, когда line закрыта и merge-back завершён, release branch можно удалить. -- Hotfix branch удаляется сразу после merge-back в целевые ветки. +- Удали `hotfix/*` локально и в `origin` после публикации GitHub Release и слияния исправления в основную ветку. +- Сохраняй целевую `release/x.y.z` и тег выпуска локально и в `origin`; не удаляй ветку при слиянии PR и не переиспользуй для другой версии. +- Отменённого кандидата не тегируй. diff --git a/docs/git-workflow/code-review.md b/docs/git-workflow/code-review.md index 16a922b..50e28ea 100644 --- a/docs/git-workflow/code-review.md +++ b/docs/git-workflow/code-review.md @@ -25,7 +25,7 @@ package: prikotov/git-workflow - Зафиксируй ожидаемый результат и критерии приёмки. - Проверь PR по правилам: [Pull Request (PR)](pull-request.md). - Несоответствия правилам PR — это `blocking`. -- Проверь результаты проверок (CI или `make check`). +- Проверь результаты проверок проекта, включая CI. - Прочитай diff целиком. - Если правила нет или оно неоднозначно — зафиксируй это и предложи отдельную задачу на уточнение конвенций проекта. - Проверяй только в рамках задачи и заявленных границ PR. diff --git a/docs/git-workflow/commits.md b/docs/git-workflow/commits.md index 0093614..d15ab9f 100644 --- a/docs/git-workflow/commits.md +++ b/docs/git-workflow/commits.md @@ -80,7 +80,7 @@ Scope указывает на область изменения, в качест - Не смешивай в одном коммите разные типы изменений. - Не смешивай в одном коммите поведение и форматирование. - Не смешивай `move/rename` и `refactor/behavior change` в одном коммите. -- Используй `git commit -m ...` без генераторов. +- Используй `git commit -m ...` без генераторов, в том числе для релизных коммитов. ## Примеры @@ -156,13 +156,11 @@ vendor/bin/validate-commit .git/COMMIT_EDITMSG | `1` | Сообщение невалидно | | `2` | Ошибка конфига или выполнения | -### Обход валидации (только для экстренных случаев) +### Исключения для валидации -```bash -git commit --no-verify -m "your commit message" -``` - -⚠️ Используйте `--no-verify` только в исключительных случаях! +- Обход хуков через `--no-verify` запрещён без явного исключения в политике проекта-потребителя. +- Исключение должно определять условия обхода и необходимые замещающие проверки; укажи основание и результаты в PR. +- Формат сообщения сохраняется при любом исключении. ### CI @@ -177,7 +175,7 @@ vendor/bin/validate-commit <(git log -1 --format=%B) 1. Выбери ``. 2. Выбери ``. -3. Сформулируй ``. +3. Сформулируй ``: `английский текст / русский текст`. 4. Создай коммит: `git commit -m "(): "`. ## Дополнительные ресурсы diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 3b8c381..75a6843 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -4,7 +4,7 @@ package: prikotov/git-workflow # Деплой (Deploy) -**Деплой (deploy)** — публикация изменений на production-сервере с необходимыми действиями: обновление кода, установка зависимостей, миграции, прогрев кэша, перезапуск или перезагрузка сервисов. +**Выкладка (Deployment, deploy)** — установка выбранной версии в рабочую среду с необходимыми действиями: обновление кода, установка зависимостей, миграции, прогрев кэша, перезапуск или перезагрузка сервисов. ## Границы ответственности @@ -16,7 +16,6 @@ package: prikotov/git-workflow ## Правила - Production deploy выполняется только по **конкретному release tag** `vX.Y.Z`. -- Деплой из `master` или `release/x.y` branch head запрещён. - Если релиз включает миграции — деплой должен учитывать порядок действий и риски. - Production incidents после деплоя закрываются через hotfix или patch release, а не через rollback. @@ -28,8 +27,9 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Подготовить и стабилизировать active `release/x.y`. -2. Создать и запушить tag `vX.Y.Z`. -3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. -4. Провести post-check: основные user-flow, логи, метрики. -5. При проблеме остановить rollout и выпустить hotfix или patch release. +**Выполняй подготовительные и завершающие действия из `docs/releases/vX.Y.Z/` на указанных там этапах.** Эти инструкции дополняют при выполнении задач. + +1. Подготовить выпуск по [процессу релиза](release.md#выпуск-релиза) или [сценарию срочного исправления](release.md#hotfix-и-patch-release), пройти обязательные проверки выбранного сценария и опубликовать тег. +2. Развернуть выбранный тег `vX.Y.Z` по инструкции выкладки проекта (runbook). +3. Проверить основные пользовательские сценарии, логи и метрики. +4. При проблеме остановить выкладку и выпустить срочное исправление (hotfix) или патч-релиз (patch release). diff --git a/docs/git-workflow/glossary.md b/docs/git-workflow/glossary.md new file mode 100644 index 0000000..28837c9 --- /dev/null +++ b/docs/git-workflow/glossary.md @@ -0,0 +1,93 @@ +--- +package: prikotov/git-workflow +--- + +# Словарь терминов (Glossary) + +Термины используются в значениях ниже. На отдельное определение можно ссылаться по якорю, например: [выкладка](#deployment). + +## Репозиторий и ветки + + +**Репозиторий (Repository)** — хранилище файлов проекта и истории их изменений в Git. + + +**Ветка (Branch)** — именованная линия разработки, указатель которой перемещается при добавлении коммитов. + + +**Основная ветка (Main branch)** — ветка по умолчанию репозитория, в которую включаются согласованные изменения и от которой готовятся обычные релизы. + + +**Релизная ветка (Release branch)** — ветка подготовки одной конкретной версии, например `release/1.2.1`. В этом процессе сохраняется после выпуска и не переиспользуется для другой версии. + + +**Коммит (Commit)** — запись в истории Git, фиксирующая состояние файлов, автора, сообщение и связь с предыдущей историей. + + +**Идентификатор коммита (Commit SHA)** — хеш, по которому Git однозначно находит конкретный коммит, независимо от последующих изменений ветки. + + +**Тег релиза (Release tag)** — именованная отметка коммита выпуска, например `v1.2.1`. В этом процессе опубликованный тег неизменяем. + +## Проверка и включение изменений + + +**Запрос на слияние (Pull Request, PR)** — предложение включить изменения из исходной ветки в целевую; содержит обсуждение, результаты проверок и решение по изменениям. + + +**Ревью кода (Code review)** — проверка предложенных изменений человеком или агентом: корректности, понятности и соответствия правилам проекта. + + +**Одобрение (Approval)** — подтверждение, что проверенное состояние изменений принято проверяющим. Разрешения на слияние и выпуск определяются отдельно по [правилам PR](pull-request.md). + + +**Слияние веток (Merge)** — объединение истории разработки для включения изменений одной ветки в другую. + + +**Объединение коммитов (Squash)** — сведение изменений нескольких коммитов в один новый коммит. + + +**Перенос коммитов (Rebase)** — повторное применение изменений коммитов к новой базе; пересозданные коммиты получают новые идентификаторы. + + +**Непрерывная интеграция (Continuous Integration, CI)** — регулярное объединение изменений, сопровождаемое автоматической сборкой и проверками. + + +**Сквозные тесты (End-to-end tests, E2E)** — проверки пользовательских сценариев целиком через публичные интерфейсы приложения. + +## Версии и релизы + + +**Версия (Version)** — определённое состояние продукта, обозначенное номером, например `1.2.1`. + + +**Семантическое версионирование (Semantic Versioning, SemVer)** — правила выбора номера `major.minor.patch` с учётом характера изменений и совместимости. Применение к версиям `0.x` и `1.x` описано в [регламенте релизов](release.md#semver-и-линии-релиза). + + +**Релиз (Release)** — опубликованная версия продукта; её публикация не означает, что она уже установлена в рабочей среде. + + +**Выпуск (Release publishing)** — публикация подготовленной версии: тега и записи GitHub Release после необходимых проверок и разрешений. Не включает [выкладку](#deployment). + + +**Запись релиза на GitHub (GitHub Release)** — запись на GitHub, связанная с тегом и содержащая описание версии; к ней могут прилагаться файлы для скачивания. Это не сам тег и не установка приложения. + + +**Фиксация состава релиза (Release cut)** — определение окончательного набора изменений при одобрении PR подготовки релиза. + + +**План релиза (Release plan)** — документ с составом версии, рисками и действиями до и после её выпуска и выкладки. + + +**Срочное исправление (Hotfix)** — исправление ошибки в рабочей версии без нарушения совместимости; готовится от тега текущей версии рабочей среды. + + +**Патч-релиз (Patch release)** — релиз совместимых исправлений ошибок с увеличением третьего числа версии, например `1.2.0` → `1.2.1`. Такое повышение версии само по себе не означает срочность выпуска. + +## Выкладка и рабочая среда + + +**Выкладка (Deployment, deploy)** — установка выбранной версии в целевую среду. В этом процессе рабочая среда обновляется по опубликованному тегу, а не по вершине ветки. + + +**Рабочая среда (Production)** — среда, в которой приложение обслуживает реальных пользователей и работает с рабочими данными. diff --git a/docs/git-workflow/index.md b/docs/git-workflow/index.md index 23b911e..8977de9 100644 --- a/docs/git-workflow/index.md +++ b/docs/git-workflow/index.md @@ -11,6 +11,7 @@ package: prikotov/git-workflow - Этот файл — оглавление раздела. - Детали и правила находятся в документах по ссылкам ниже. +- [Словарь терминов (Glossary)](glossary.md) - [Ветки (Branches)](branches.md) - [Коммиты (Commits)](commits.md) - [Pull Request (PR)](pull-request.md) diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index f3970ed..262a278 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -4,7 +4,7 @@ package: prikotov/git-workflow # Запрос на слияние (Pull Request) -**Pull Request (PR)** — предложенный набор изменений из рабочей ветки в целевую ветку (`master` или активную `release/x.y`), проходящий проверки и `Code Review`. +**Pull Request (PR)** — предложенный набор изменений из рабочей ветки в целевую, проходящий проверки и `Code Review`. ## Границы ответственности @@ -16,8 +16,8 @@ package: prikotov/git-workflow ## Правила -- Запрещены прямые правки в `master`. -- Одна задача — один PR, либо одна подзадача, если задача большая. +- Вноси изменения в основную ветку только через PR. Коммить в рабочих ветках `task/*`, `release/*` и `hotfix/*` только по запросу пользователя. +- Одна обычная задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. - Не добавляй в PR изменения "заодно". @@ -38,36 +38,43 @@ package: prikotov/git-workflow ## Выбор base branch -- `task/*` для обычной разработки → `master`. -- Stabilization fixes для текущего релиза → активная `release/x.y`. -- `hotfix/*` → активная `release/x.y`, если release line ещё жива; дополнительно обязателен merge-back в `master`. -- Если активная `release/x.y` уже закрыта, hotfix оформляется как patch line от production tag, а merge-back в `master` выполняется отдельным PR сразу после выпуска patch release. +- На основную ветку указывает `origin/HEAD` по [правилам веток](branches.md#целевая-модель). +- Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. +- Обычный релиз: отдельная `release/x.y.z` от актуальной основной ветки → PR в основную ветку до публикации тега. +- Срочное исправление: `hotfix/x.y.z-` и `release/x.y.z` нового выпуска создаются от текущего рабочего тега; PR направляй из `hotfix/*` в эту новую релизную ветку до публикации нового тега. Пример: для исправления `v1.2.0` цель PR — `release/1.2.1`, не `release/1.2.0`. Полный порядок — в [сценарии срочного исправления](release.md#hotfix-и-patch-release). +- Возврат срочного исправления: отдельный PR из этой `release/x.y.z` в основную ветку после выпуска, без временной ветки. +- До срочного выпуска не синхронизируй `hotfix/*` и целевую `release/x.y.z` с основной веткой. Если для возврата нужны доработки, выполни их в релизной ветке после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. + +## Обязательные проверки + +- По умолчанию перед PR должны успешно пройти проверки проекта, в том числе для `docs-only` и служебных изменений. +- Набор проверок и команды запуска бери из документации проекта. Если они не определены, уточни у пользователя. +- Пропуск или замена проверки допустимы только по явной политике проекта-потребителя (например, в его `AGENTS.md`): должны быть указаны применимые категории изменений и необходимые проверки вместо пропущенной. +- Отсутствие команды или сбой окружения не разрешают пропуск проверки. +- В PR укажи выполненные команды, результаты и ссылку на применимое проектное исключение, если оно использовано. +- Исключение для одной проверки не отменяет остальные обязательные проверки и CI, если политика явно не определяет иное. ## Создание PR -- Определи, это `docs-only` правка или нет. -- Если это не `docs-only` — **обязательно** запусти `make check`. -- `make check` должен быть зелёный. -- Если это `docs-only` — укажи в PR, что `make check` пропущен по исключению. +- Выполни [обязательные проверки](#обязательные-проверки). - Сделай self-review: [Ревью кода (Code Review)](code-review.md). -- После создания PR синхронизируй задачу в `todo/`: заполни поле `pr`, переведи `Статус` в `review`. - Используй CLI-инструменты: `git`, `gh`. - Сделай push: `git push -u origin HEAD`. -- Создай PR через `gh pr create --head $(git branch --show-current)`. +- Создай PR с [выбранной базой](#выбор-base-branch): `gh pr create --base --head "$(git branch --show-current)"`. - Тело PR передавай через `gh pr create --body-file`. - Предпочитай `--body-file -` (stdin) или файл в `tmp/`. -- После создания PR обнови поле `PR` в задаче (`todo/...`) ссылкой или номером созданного PR. +- Связь задачи с PR и переходы статусов веди по правилам `todo-md` проекта. ## Оформление PR - Заголовок PR: английский, кратко отражает суть. - Для release и hotfix PR явно укажи: - - release line (`release/x.y`); + - релизную ветку `release/x.y.z` либо ветку срочного исправления `hotfix/*`; - production tag, который исправляем или выпускаем; - - нужен ли merge-back в `master`; + - порядок выпуска и включения изменений в основную ветку; - какие изменения сознательно **не** входят в этот релиз. - Описание PR включает: - - если задачи в `todo/` ещё нет — оформи её по правилам: [todo/AGENTS.md](../../todo/AGENTS.md); + - если проект использует `todo-md` и задачи ещё нет — оформи её по установленным в проекте правилам `todo-md`; - постановку задачи из prompt; - постановку задачи из `todo/.todo.md` (если есть); - цель и причину изменений; @@ -91,26 +98,30 @@ package: prikotov/git-workflow ## Подготовка PR -- Дождись зелёного CI на созданном PR. -- Переведи задачу в `done` по правилам проекта и запушь в ту же ветку. -- Только после перевода задачи в `done` запроси апрув (approve) у пользователя. -- После апрува в PR-ветку не пушится ничего — только `gh pr merge`. +- Заверши все изменения в PR-ветке до запроса окончательного одобрения (approve), включая релизные файлы и служебные обновления задачи по правилам `todo-md` проекта. +- Если PR завершает реализацию задачи, оформи `done` по правилам `todo-md` проекта и опубликуй изменения до окончательного одобрения. +- В PR постановки оставь будущую задачу в `todo` или `backlog`. Если постановка оформлена отдельной задачей, заверши только её. +- После последнего push дождись зелёного CI и выполни обязательные проверки окончательного состояния PR. +- Запроси одобрение проверенного состояния PR. +- После одобрения не меняй PR-ветку, включая служебные данные. +- После доработок или синхронизации повтори проверки и запроси новое одобрение до merge. ## Перед merge -- Убедись, что задача переведена в `done`. -- Убедись, что пользователь апрувнул PR и подтвердил merge. +- Убедись, что задача оформлена по правилам `todo-md` проекта; для PR с завершённой реализацией её статус — `done`. +- Убедись, что проверки и одобрение относятся к окончательному состоянию PR, а пользователь подтвердил merge. ## Выполнение merge - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- После merge hotfix в `release/x.y` не забудь сделать merge-back в `master`. +- Слей PR подготовки обычного релиза или срочного исправления до публикации тега. +- PR возврата срочного исправления из `release/x.y.z` в основную ветку слей после выпуска. Не удаляй исходную релизную ветку при слиянии. ## После merge -- После merge PR в `master` переключись на `master` и обнови его: `git pull origin master`. -- После merge PR в `release/x.y` переключись на эту release line только если продолжается стабилизация; иначе вернись в `master`. -- Удали рабочую ветку локально и в `origin`. +- После merge PR в основную ветку переключись на неё и актуализируй её из `origin`. +- Удали `task/*` локально и в `origin`. Удали `hotfix/*` после выпуска и включения исправления в основную ветку. +- Сохраняй все `release/*` локально и в `origin`, а также теги выпусков. Не переиспользуй релизную ветку для другой версии. - Проверь, что рабочее дерево чистое: `git status`. - Предложи пользователю следующую задачу. diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 6eb3d85..d93aea2 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -8,27 +8,42 @@ package: prikotov/git-workflow ## Чеклист подготовки релиза -- Состав релиза согласован, лишние изменения остаются в `master`. +Для обычного релиза, включая `patch`, из основной ветки `master`/`main`. + +- Согласован состав релиза из актуальной основной ветки. - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. -- От актуального `master` создана одна активная `release/x.y`. -- Все PR для стабилизации целятся в `release/x.y`. -- Для релиза выполнены `make check` и `make tests-e2e`. -- `CHANGELOG.md` и описание релиза подготовлены. +- Для выбранной полной версии создана отдельная `release/x.y.z` от актуальной основной ветки по [процессу релиза](release.md#1-финализация-в-релизной-ветке). Ветка другого выпуска не переиспользована. +- Документы обновлены под состав релиза и содержат действия до и после выпуска. Существующий `release-plan.md` не перезаписан шаблоном. +- Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y.z` вручную, без автоматического тега. +- PR (запрос на слияние) открыт из `release/x.y.z` в основную ветку; синхронизация завершена до окончательного одобрения. +- Все изменения, включая данные задачи, закоммичены до окончательных проверок и одобрения PR. +- Перед релизом выполнены проверки проекта с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты; проверки успешны. +- Автоматические проверки PR (CI) успешны. Пользователь одобрил проверенный PR и подтвердил слияние; PR слит через GitHub. +- Коммит слияния входит в историю основной ветки и совпадает по содержимому с одобренным коммитом `release/x.y.z`; оба SHA зафиксированы: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). +- После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). +- Релизная ветка и тег сохраняются после выпуска. ## Чеклист срочного исправления - Определён текущий тег релиза на production `vX.Y.Z`. -- `hotfix/x.y.z-` создан от тега production, а не от `master`. +- Рабочая ветка `hotfix/x.y.z-` и целевая `release/x.y.z` нового выпуска созданы от текущего рабочего тега, не от основной или сохранённой релизной ветки. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Зафиксирован план возврата изменений в активную `release/x.y` и `master`. -- Проверки для срочного исправления пройдены до выпуска патч-релиза. +- Имя ветки и тег соответствуют новой полной версии. Ветки предыдущих и параллельно готовящихся выпусков не переиспользованы и не перезаписаны. +- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y.z` завершена до одобрения. +- Перед срочным выпуском выполнены проверки по правилам проекта; проверки и CI успешны. +- Если пользователь явно запросил сквозные тесты, они выполнены успешно; без запроса не запускались. +- Проверенный PR из `hotfix/*` в `release/x.y.z` нового выпуска одобрен и слит через GitHub с подтверждением пользователя. +- Коммит слияния входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. +- Выпуск разрешён. Новый тег отмечает проверенный результат слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +- После выпуска запланирован отдельный PR возврата из этой `release/x.y.z` в основную ветку, без временной ветки. Адаптация и конфликты не меняют опубликованный тег. +- После возврата исправления `hotfix/*` удаляется, релизная ветка и тег сохраняются. ## Чеклист выкладки -- Выбран тег релиза `vX.Y.Z` для выкладки. -- Создан и заполнен `docs/releases/vX.Y.Z/release-plan.md`. +- Выбран опубликованный неизменяемый тег `vX.Y.Z`: для обычного релиза он указывает на согласованный коммит основной ветки, для срочного исправления — на коммит соответствующего патч-релиза. +- Актуальный `docs/releases/vX.Y.Z/release-plan.md` присутствует в версии, отмеченной этим тегом. - Web и Workers будут выкачены на один и тот же тег. - В `release-plan.md` зафиксированы миграции, порядок их применения и риск окна несовместимости. - В `release-plan.md` зафиксирован план исправления без отката. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 9f5d589..58bf20a 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,15 +4,16 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Этот гайд фиксирует release model проекта TasK: `master` как integration branch, одна active `release/x.y`, production deploy по immutable `tag` `vX.Y.Z`. +## Модель релизов -## Release model - -- `master` содержит текущую интеграцию задач и может опережать production. -- Перед production выпуском из выбранного commit в `master` создаётся `release/x.y`. -- В `release/x.y` допускаются только stabilizing changes: bugfix, release docs, безопасные мелкие правки. -- Production всегда разворачивается по **конкретному tag**, а не по branch head. -- Одновременно поддерживается только одна active `release/x.y`. +- Для каждого [выпуска](glossary.md#release-publishing) создавайте отдельную `release/x.y.z`, включая каждый патч. Сохраняйте все релизные ветки и теги, не переиспользуйте ветку для другой версии. +- Финализируйте обычный релиз в `release/x.y.z` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. +- Для обычного релиза направляйте запрос на слияние (Pull Request, PR) из `release/x.y.z` в основную ветку. +- После проверок и одобрения слейте PR обычного релиза. Поставьте тег на проверенный коммит слияния. +- Изменяйте основную ветку только через PR. Коммитьте в рабочих ветках только по запросу пользователя. +- Разворачивайте рабочую среду (production) по неизменяемому тегу `vX.Y.Z`, не по последнему коммиту ветки. +- Одновременно готовьте один обычный релиз; срочное исправление может готовиться параллельно. Сохранённые ветки завершённых выпусков этому не мешают. +- Для срочного исправления от рабочего тега следуйте [отдельному сценарию](#hotfix-и-patch-release). ## SemVer и линии релиза @@ -31,61 +32,33 @@ package: prikotov/git-workflow Несовместимость в версии `0.x` обязательно отмечается в `CHANGELOG.md` и плане релиза, хотя повышает `minor`, а не `major`. Если релиз содержит изменения разных типов, выбирается наибольшее требуемое повышение версии. -Тип релиза определяется по истории Conventional Commits: `fix` требует `patch`, `feat` — `minor`, а `BREAKING CHANGE` или `!` — `minor` при текущей версии `0.x` и `major` начиная с `1.0.0`. В спорных случаях используйте явные `make release-*`. +Тип релиза определяется по истории Conventional Commits: `fix` требует `patch`, `feat` — `minor`, а `BREAKING CHANGE` или `!` — `minor` при текущей версии `0.x` и `major` начиная с `1.0.0`. Выбранную по этим правилам версию явно передавайте генератору. -- `patch` сохраняет текущую release line. -- `minor` и `major` открывают новую `release/x.y`. +Обычный патч-релиз также выпускается из актуальной основной ветки. `patch` сохраняет номер линии `x.y`, а `minor` и `major` меняют его. ## Подготовка коммитов -Используйте интерактивный помощник: - -```bash -make prepare-commit -``` - -Если helper падает, сформируйте заголовок вручную по Conventional Commits: +Сообщения всех коммитов, включая релизные, готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. ```bash -git commit -m "type(scope): description" +git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ``` Примеры: -- `feat(auth): add OAuth2 login for Google` -- `fix(ui): align submit button on mobile` -- `docs(release): describe hotfix merge-back` -- `feat!: remove legacy v1 endpoints` +- `feat(auth): add OAuth2 login for Google / добавить вход через Google OAuth2` +- `fix(ui): align submit button on mobile / выровнять кнопку отправки на мобильных устройствах` +- `docs(release): describe hotfix merge-back / описать возврат срочного исправления` +- `feat(api)!: remove legacy v1 endpoints / удалить устаревшие эндпоинты v1` ## Release cut -Когда Product Owner и Team Lead зафиксировали состав релиза: - -```bash -git switch master -git pull origin master -git switch -c release/x.y -git push -u origin release/x.y -``` - -После открытия `release/x.y`: -- все новые feature PR продолжают идти в `master`; -- в `release/x.y` попадают только stabilizing PR; -- если найден дефект production, hotfix стартует от текущего production tag и затем вливается в `release/x.y` и `master`. +Зафиксируйте состав релиза при окончательном одобрении PR. При изменении состава повторите проверки и запросите новое одобрение по [правилам PR](pull-request.md#подготовка-pr). ## План релиза -Для каждого production release перед deploy создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. - -- место хранения: `docs/releases/`; -- шаблон: [release-plan.template.md](./templates/release-plan.template.md). -- без заполненного `release-plan.md` deploy не начинается. +Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. -Базовое создание документа после определения тега релиза: - -```bash -mkdir -p docs/releases/vX.Y.Z -cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/release-plan.md -``` +При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по шаблону [обычного релиза](./templates/release-plan.template.md) или [срочного исправления](./templates/hotfix-release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. В `release-plan.md` обязательно зафиксируйте: - состав релиза и его границы; @@ -94,89 +67,138 @@ cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/rel - проверки после deploy; - план действий при проблеме после релиза через hotfix или patch release. +Результаты проверок и выкладки фиксируйте в комментариях к PR подготовки, не меняя одобренную ветку или тег. + ## Работа с CHANGELOG -Для предпросмотра изменений: +Генерируйте файлы в `release/*`, для срочного исправления — в `hotfix/*`. Если проект использует `marcocesarato/php-conventional-changelog`, запускайте его без автоматического коммита и тега: ```bash -make changelog -git diff CHANGELOG.md +php vendor/bin/conventional-changelog --ver="X.Y.Z" --no-tag --merged +git diff ``` +- Замените `X.Y.Z` выбранной версией без префикса `v`; `--merged` ограничивает историю коммитами, достижимыми из `HEAD`. +- Не используйте `--commit`, `--commit-all` или `--amend`. Проверьте конфигурацию `.changelog` и её callbacks: они тоже не должны создавать коммиты, теги или выполнять публикацию. +- Команда изменяет файлы. Проверьте весь diff, включая `CHANGELOG.md` и файлы версий. +- Если генератор не установлен, подготовьте файлы вручную по тем же правилам. Этот пакет не поставляет генератор или команды подготовки релиза. +- Не запускайте проектные команды подготовки релиза или CHANGELOG, пока не проверены их действия. + `CHANGELOG.md` должен оставаться коротким: - заголовок релиза; - compare link; -- одна короткая summary-строка. +- одна короткая summary-строка; +- явное указание несовместимости, если она есть, включая версии `0.x`. Подробные notes публикуются в GitHub Release. ## Выпуск релиза -Перед релизом: +### 1. Финализация в релизной ветке + +Выберите версию по SemVer и создайте `release/x.y.z` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке, проверив её базу и состав. Для нового выпуска имя ветки и тег должны быть свободны локально и в `origin`; при конфликте остановитесь, не перезаписывайте их. + +Замените `x.y.z` полной версией выпуска: ```bash -make check -make tests-e2e +git fetch origin && + # Обновить локальный указатель основной ветки по данным origin. + git remote set-head origin --auto && + # Получить её имя, например origin/main. + base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && + # Убрать префикс origin/ и переключиться на локальную ветку. + git switch "${base#origin/}" && + git pull --ff-only origin "${base#origin/}" && + git switch -c release/x.y.z && + git push -u origin release/x.y.z ``` -Релиз выполняется **на active `release/x.y`**, а не на `master`. +1. В `release/x.y.z` внесите исправления, обновите `CHANGELOG.md`, файлы версий и релизные документы. +2. Проверьте diff и создайте коммиты вручную по [commits.md](commits.md). +3. Откройте PR **из `release/x.y.z` в основную ветку** по [правилам PR](pull-request.md). +4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните проверки проекта и обязательный предрелизный запуск сквозных тестов; дождитесь успеха. Проектные исключения для других проверок не отменяют сквозные тесты. +5. Зафиксируйте SHA проверенного состояния `release/x.y.z`. Дождитесь успешных автоматических проверок PR (CI), одобрения и подтверждения слияния пользователем. Выполните слияние через GitHub. Доработки требуют [повторного одобрения](pull-request.md#подготовка-pr). + +### 2. Проверка коммита выпуска -Вариант A — patch по умолчанию: +Получите SHA коммита слияния PR из GitHub. Сравните его содержимое с одобренным коммитом `release/x.y.z`. Не подставляйте текущий `HEAD` основной ветки. + +Подставьте полные SHA коммита слияния и одобренного коммита релизной ветки: ```bash -make release +release_commit=VERIFIED_MERGE_SHA +release_head=APPROVED_RELEASE_SHA +git fetch origin && + # Обновить локальный указатель основной ветки по данным origin. + git remote set-head origin --auto && + git merge-base --is-ancestor "$release_commit" origin/HEAD && + git diff --exit-code "$release_head" "$release_commit" -- ``` -Вариант B — явный тип: +При ошибке или различиях остановите выпуск. Согласуйте состав и проверьте изменения кода, зависимостей и конфигурации. Доработки слейте новым PR из релизной ветки в основную. Если изменился только SHA, а содержимое совпадает, повторный полный прогон и отдельный CI не требуются. + +### 3. Создание и публикация тега + +После обязательных проверок и разрешения на выпуск создайте тег **на зафиксированном коммите** из шага 2 либо [сценария срочного исправления](#hotfix-и-patch-release). Подставьте его полный SHA в `VERIFIED_RELEASE_SHA`, выбранную версию — в `X.Y.Z`: ```bash -make release-patch -make release-minor -make release-major +release_commit=VERIFIED_RELEASE_SHA +git tag -a vX.Y.Z "$release_commit" -m "Release vX.Y.Z" && + git push --no-follow-tags origin refs/tags/vX.Y.Z:refs/tags/vX.Y.Z ``` -Что делает release команда: -- обновляет `CHANGELOG.md`; -- определяет или принимает версию; -- делает release commit; -- создаёт git tag `vX.Y.Z`. +- Публикуйте только выбранный тег; `git push --tags` запрещён. +- Тег production неизменяем: не перемещайте, не перезаписывайте и не публикуйте его с `--force`. +- После слияния не запускайте генератор и не создавайте релизный коммит в основной ветке. + +### 4. GitHub Release -После генерации: -1. проверьте `CHANGELOG.md`; -2. создайте и заполните `docs/releases/vX.Y.Z/release-plan.md`; -3. если блок слишком длинный, вынесите подробности в GitHub Release notes; -4. запушьте release branch и tags: +Убедитесь, что опубликованный тег указывает на выбранный коммит релиза. Создайте GitHub Release только для уже существующего удалённого тега: ```bash -git push origin release/x.y -git push origin --tags +gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ``` -5. создайте GitHub Release: +Или используйте `--generate-notes` вместо `--notes-file`. Описание подготовьте до публикации; `--verify-tag` запрещает неявное создание тега. + +## Hotfix и patch release + +Определите текущий тег рабочей среды `vX.Y.Z` и версию нового выпуска `x.y.z`. Создайте `release/x.y.z` нового выпуска от этого тега, не от вершины старой релизной ветки. Например: исправление `v1.2.0` → новая `release/1.2.1` → тег `v1.2.1`; `release/1.2.0` не меняется. + +Для нового выпуска имя ветки и тег должны быть свободны локально и в `origin`: ```bash -gh release create vX.Y.Z --notes-file tmp/release-vX.Y.Z.md +git fetch origin --tags --prune && + git switch -c release/x.y.z vX.Y.Z && + git push -u origin release/x.y.z ``` -или +Если подготовка этого выпуска уже идёт, продолжайте в его ветке, проверив базу и состав. При занятой версии или несогласованных изменениях остановитесь и уточните дальнейшие действия. Не переиспользуйте и не перезаписывайте ветки других выпусков. + +До выпуска не подтягивайте основную ветку в `hotfix/*` и целевую `release/x.y.z`. + +При срочном исправлении запускайте сквозные тесты только по явному запросу пользователя. Если затронут критический пользовательский сценарий, предложите точечный запуск вместо полного прогона сквозных тестов. + +1. Создайте `hotfix/x.y.z-` от того же рабочего тега по [правилам веток](branches.md#hotfix-branch); `x.y.z` — версия нового выпуска. +2. Исправьте проблему и подготовьте файлы нового патч-релиза в `hotfix/*`. Убедитесь, что CI проекта запускается для целевой `release/x.y.z`. Откройте PR **из `hotfix/*` в `release/x.y.z` нового выпуска**. +3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y.z`. Завершите все правки, выполните проверки по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. +4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`: ```bash -gh release create vX.Y.Z --generate-notes +release_branch=release/x.y.z +release_commit=VERIFIED_HOTFIX_MERGE_SHA +hotfix_head=APPROVED_HOTFIX_SHA +git fetch origin && + git merge-base --is-ancestor "$release_commit" "origin/$release_branch" && + git diff --exit-code "$hotfix_head" "$release_commit" -- ``` -## Hotfix и patch release - -Срочный hotfix не делается от `master`. +При ошибке остановите выпуск. Доработки проведите через новый PR из `hotfix/*` в ту же `release/x.y.z` с повторными проверками и одобрением. Изменение только SHA при совпадающем содержимом не требует полного повторного прогона или отдельного CI. -Базовый flow: -1. определить текущий production tag `vX.Y.Z`; -2. создать `hotfix/x.y.z-` от этого tag; -3. исправить проблему и провести обязательные проверки; -4. влить hotfix в active `release/x.y`; -5. выпустить patch release `vX.Y.(Z+1)`; -6. выполнить merge-back hotfix changes в `master`. +5. После разрешения на выпуск [опубликуйте новый тег](#3-создание-и-публикация-тега) **на проверенном результате слияния**. Выпустите патч по этому тегу. +6. Сразу после выпуска откройте отдельный PR **из этой `release/x.y.z` в основную ветку**. Выполните проверки, получите одобрение и подтверждение слияния. Если нужны адаптация или разрешение конфликтов, внесите их в эту релизную ветку после выпуска и повторите проверки и одобрение. Временная ветка для возврата не нужна. Не меняйте опубликованный тег. -Если active `release/x.y` уже закрыта, hotfix всё равно стартует от production tag, а merge-back в `master` делается отдельным PR сразу после patch release. +Исправление попадёт в ветку следующего обычного релиза при её синхронизации с основной веткой. После выпуска и возврата удалите `hotfix/*`, сохраните `release/x.y.z` и тег. Для следующего срочного исправления создайте новые ветки от текущего рабочего тега, не от изменённой вершины сохранённой ветки. ## Recovery Policy @@ -187,7 +209,5 @@ gh release create vX.Y.Z --generate-notes ## Рекомендации команды -- Перед release cut проверьте, что в `master` нет случайных незавершённых изменений, которые не должны попасть в релиз. - Для hotfix PR всегда явно фиксируйте merge-back plan. -- Не открывайте вторую `release/x.y`, пока не закрыта текущая line. - Для release и hotfix используйте чеклисты: [Чеклисты релиза и hotfix](release-checklists.md). diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 901132d..a2c9524 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -4,20 +4,19 @@ package: prikotov/git-workflow # Артефакты релиза -Этот раздел описывает документы, которые создаются для конкретного production релиза. - ## Структура -- `docs/git-workflow/templates/release-plan.template.md` — шаблон плана релиза. +- `docs/git-workflow/templates/release-plan.template.md` — шаблон плана обычного релиза. +- `docs/git-workflow/templates/hotfix-release-plan.template.md` — шаблон плана срочного исправления. - `docs/releases/vX.Y.Z/release-plan.md` — заполненный план релиза для конкретного тега релиза. ## Правила -- Для каждого production релиза перед deploy создаётся каталог `docs/releases/vX.Y.Z/`. -- Минимально обязательный файл в каталоге релиза: `release-plan.md`. -- `release-plan.md` фиксирует состав релиза, риски, миграции, порядок deploy, post-check и план действий через hotfix или patch release. -- Для `hotfix` и `patch release` создаётся отдельный каталог по новому тегу релиза. +- Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. +- При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. +- Заполните обязательный `release-plan.md`: состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. -## Шаблон +## Шаблоны -- [Шаблон плана релиза](../templates/release-plan.template.md) +- [План обычного релиза](../templates/release-plan.template.md) +- [План срочного исправления](../templates/hotfix-release-plan.template.md) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md new file mode 100644 index 0000000..40fc199 --- /dev/null +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -0,0 +1,60 @@ +# План срочного исправления [тег релиза] + +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) срочного исправления проверьте полноту и актуальность плана. + +## Метаданные + +- Тег релиза: [тег в формате `vX.Y.Z`] +- Тип выпуска: `hotfix` +- Причина срочного исправления: [описание ошибки] +- База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] +- Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] +- PR срочного исправления в `release/x.y.z` (слить до создания тега): [ссылка на PR в ветку нового выпуска] +- PR включения срочного исправления в основную ветку (открыть после публикации GitHub Release): [ссылка на PR после его создания] +- Ответственный: [имя или ссылка на профиль роли] + +## Состав + +- Включённые PR: [ссылки на PR] +- Включённые задачи: [ссылки на задачи] + +## Риски + +- Основные риски: [риски исправления и выкладки, меры их снижения] +- Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] +- Порядок применения миграций: [команды и последовательность применения] + +## Порядок deploy + +1. Web +2. Workers + +## План проверок перед выкладкой + +- Выполнить проверки по правилам проекта; дождаться успешного результата +- Запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок +- До создания тега проверить, что PR из `hotfix/*` слит в `release/x.y.z` нового выпуска +- Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки +- Убедиться, что согласованный тег опубликован в `origin` +- Проверить необходимые изменения переменных окружения +- Проверить готовность миграций и безопасность порядка обновления кода и данных +- Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] + +## План проверок после выкладки + +- Проверить, что исправление включено в основную ветку через PR из этой `release/x.y.z` +- Основные пользовательские сценарии и ожидаемые результаты: [шаги проверки и признаки успеха] +- Проверяемые логи и признаки ошибок: [источники логов и сообщения, требующие реакции] +- Ожидаемое состояние очередей и обработчиков: [проверяемые показатели и допустимые значения] +- Способ проверки версии сборки и идентификатора коммита (SHA): [команда или место проверки и ожидаемые значения] + +## Действия при проблеме после релиза + +- Откат: не используется +- Действия при проблеме: [как исправить проблему и проверить результат] +- Ответственный инженер: [имя или ссылка на профиль роли] +- Канал коммуникации / задача: [ссылка на канал или задачу для координации исправления] + +## Заметки + +- Дополнительные инструкции: [особые действия для этого выпуска] diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 2791fc9..09458dd 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,55 +1,60 @@ -# План релиза vX.Y.Z +# План обычного релиза [тег релиза] + +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. ## Метаданные -- Тег релиза: `vX.Y.Z` -- Тип повышения версии (указать одно: `major`, `minor` или `patch`): -- Обоснование выбранной версии: -- Линия релиза: `release/x.y` -- Исходная ветка: -- Ответственный: -- Плановая дата deploy: +- Тег релиза: [тег в формате `vX.Y.Z`] +- Тип повышения версии: [`major`, `minor` или `patch`] +- Обоснование выбранной версии: [причина повышения версии с учётом совместимости] +- База рабочей ветки: [актуальная основная ветка по `origin/HEAD`] +- Рабочая ветка: [ветка в формате `release/x.y.z`] +- PR подготовки релиза в основную ветку (слить до создания тега): [ссылка на PR] +- Ответственный: [имя или ссылка на профиль роли] +- Плановая дата выкладки: [дата, время и часовой пояс] ## Состав -- Включённые PR: -- Включённые задачи: -- Вне состава релиза: +- Включённые PR: [ссылки на PR] +- Включённые задачи: [ссылки на задачи] ## Риски -- Основные риски: -- Наличие миграций данных: -- Порядок применения миграций: -- Риск окна несовместимости: -- Замечания по обратной совместимости: +- Основные риски: [риски изменений и выкладки, меры их снижения] +- Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] +- Порядок применения миграций: [команды и последовательность применения] +- Несовместимые изменения: [перечень изменений и действия для перехода либо подтверждение сохранения совместимости] ## Порядок deploy 1. Web 2. Workers -## Проверки перед deploy +## План проверок перед выкладкой -- Тег релиза запушен в `origin` -- Подготовлены обязательные изменения в env -- В документе зафиксированы миграции, порядок их применения и риск окна несовместимости -- Подготовлены команды health-check +- Выполнить проверки по правилам проекта; дождаться успешного результата +- Обязательно выполнить сквозные тесты; дождаться успешного результата +- До создания тега проверить, что PR из `release/x.y.z` слит в основную ветку +- Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y.z` +- Убедиться, что согласованный тег опубликован в `origin` +- Проверить необходимые изменения переменных окружения +- Проверить готовность миграций и безопасность порядка обновления кода и данных +- Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] -## Проверки после deploy +## План проверок после выкладки -- Основные пользовательские сценарии: -- Логи: -- Очереди и воркеры: -- Build version и git SHA: +- Основные пользовательские сценарии и ожидаемые результаты: [шаги проверки и признаки успеха] +- Проверяемые логи и признаки ошибок: [источники логов и сообщения, требующие реакции] +- Ожидаемое состояние очередей и обработчиков: [проверяемые показатели и допустимые значения] +- Способ проверки версии сборки и идентификатора коммита (SHA): [команда или место проверки и ожидаемые значения] ## Действия при проблеме после релиза - Откат: не используется -- Стратегия исправления: `hotfix` / `patch release` -- Ответственный инженер: -- Канал коммуникации / задача: +- Действия при проблеме: [как исправить проблему и проверить результат] +- Ответственный инженер: [имя или ссылка на профиль роли] +- Канал коммуникации / задача: [ссылка на канал или задачу для координации исправления] ## Заметки -- Дополнительные инструкции: +- Дополнительные инструкции: [особые действия для этого выпуска] diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md new file mode 100644 index 0000000..10c615f --- /dev/null +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -0,0 +1,257 @@ +--- +type: docs +created: 2026-09-11 03:45:03 (1789098303) +due: +started: 2026-09-11 03:46:53 (1789098413) +completed: 2026-09-14 04:03:12 (1789358592) +cancelled: +value: V2 +complexity: C2 +priority: P1 +cost_plan: +cost_fact: +depends_on: +epic: +author: Технический писатель (pi) +assignee: Технический писатель (pi) +branch: task/align-workflow-instructions +pr: https://github.com/prikotov/git-workflow/pull/10 +status: done +--- + +# TASK-docs-align-workflow-instructions: Align workflow instructions + +## 0. Простое описание (Human Brief) + +### Проблема простыми словами (Problem) +Инструкции пакета одновременно запрещают прямые изменения релизной ветки и предписывают создавать в ней релизный коммит. Общая инструкция синхронизации также может затянуть новые функции в стабилизируемый релиз. Проекты-потребители получают несовместимые правила публикации. + +### Варианты или путь решения (Solution Sketch) +Согласовать документы в исходном пакете: подготовка релиза проходит через запрос на слияние, рабочие ветки синхронизируются со своей базой, а правила проверок и подготовки коммитов имеют один источник. + +### Ожидаемый результат (Expected Result) +Исполнитель может подготовить задачу и релиз без прямых коммитов в целевые ветки и без неоднозначного выбора проверок. + +## 1. Концепция и Цель (Concept and Goal) + +### История (User Story) +> Как владелец проекта-потребителя, я хочу согласованные инструкции Git, чтобы агент не обходил одобрение изменений и не смешивал релизные линии. + +### Цель по SMART (Goal) +В одном PR согласовать инструкции веток, коммитов, проверок и выпуска релиза. Проверить документацию, установку пакета во временный каталог и обязательную проверку Composer до публикации. + +## 2. Контекст и Границы (Context and Scope) +- Исходники: `docs/git-workflow/branches.md`, `commits.md`, `pull-request.md`, `release.md`, связанные чеклисты и шаблоны только при прямом конфликте. +- Исправления требуются в исходном пакете, а не в игнорируемых копиях TasK. +- Пользователь подтвердил два отдельных PR в пакетах, релизы через PR и отсутствие фактического слияния/выпуска версий. +- Не менять код инструментов, зависимости, настройки защиты веток и документы других репозиториев. + +## 3. Требования, MoSCoW (Requirements) +### 🔴 Обязательно (Must Have) +- [x] Для каждого выпуска, включая каждый патч, создавать отдельную `release/x.y.z`; сохранять все релизные ветки и теги, не переиспользовать ветку для другой версии. +- [x] Финализировать обычный релиз в `release/x.y.z` от актуальной основной ветки; PR направлять из неё в основную ветку до выпуска. Срочное исправление от рабочего тега описывать отдельно. +- [x] Включать изменения в основную ветку только через PR; сохранить коммиты в `release/*` обычного релиза без промежуточной ветки. Срочное исправление сливать через PR из `hotfix/*` в `release/x.y.z` нового выпуска до нового тега; обе ветки создавать от текущего рабочего тега. +- [x] После срочного выпуска возвращать исправление отдельным PR из его релизной ветки в основную, без временной ветки. Конфликты разрешать в релизной ветке после выпуска, тег не менять; следующий hotfix начинать от рабочего тега, не от изменённой вершины ветки. +- [x] Разрешить создавать и дополнять релизные документы заранее в рамках обычных задач; при финализации проверять накопленное, не заменять существующий план шаблоном. +- [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. +- [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. +- [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. +- [x] По подтверждённому запросу пользователя оставить сквозные тесты обязательными для обычного релиза, а для срочного исправления запускать только по явному запросу. Сохранить требования к проверкам проекта и CI без привязки к названиям команд. +- [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. +- [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. +- [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. +- [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками без отдельной инструкции по их заполнению. +- [x] В `branches.md` определять основную ветку через актуальный `origin/HEAD`, без ручной подстановки `master`/`main`. +- [x] Для синхронизации веток использовать только `merge`, не переписывая существующие коммиты. +- [x] Добавить словарь документации: русский термин, английский в скобках и пояснение через тире; обеспечить ссылки на отдельные определения. +### ⚫ Won't Have (Не будем делать) +- Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. +- Массово переписывать документацию вне выявленных противоречий. + +## 4. План реализации (Implementation Plan) +1. [x] Сверить документы пакета и реальные параметры упоминаемых инструментов. +2. [x] Точечно согласовать ветки, подготовку коммитов, проверки и релиз через PR. +3. [x] Проверить ссылки, выполнить `composer validate --strict` и проверку установки документации во временный каталог. +4. [x] Провести личную вычитку без делегирования, устранить замечания. +5. [x] Создать PR с меткой `pi`, заполнить ссылку, дождаться CI и подготовить задачу к приёмке. + +## 5. Критерии приёмки (Definition of Done) +- [x] Все обязательные требования выполнены; инструкции не требуют прямой записи в целевые ветки. +- [x] Проверки Composer и документации успешны; личная вычитка не выявила блокирующих замечаний. +- [x] PR открыт, задача связана с ним и готова к приёмке; версии и теги не выпускались. + +## 6. Самопроверка (Verification) +```bash +composer validate --strict +git diff --check +``` +Дополнительно: установка документации через `bin/git-workflow-init` в отдельный временный каталог и проверка новых относительных ссылок. CI пакета выполняет `composer validate --strict`. Проверить отсутствие приватных зависимостей в `composer.json`. + +### Результат выполнения + +- Согласованы `glossary.md`, `index.md`, `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md`, `templates/release-plan.template.md` и `templates/hotfix-release-plan.template.md` в `docs/git-workflow/`. +- Каждый выпуск получает отдельную сохраняемую `release/x.y.z` и неизменяемый тег. Документы накапливаются в обычных задачах; обычный релиз финализируется в своей ветке от актуальной основной, затем PR сливается в основную до тега. Для срочного исправления обе новые ветки создаются от рабочего тега: PR `hotfix/*` → новая `release/x.y.z` → тег и выпуск → PR из неё в основную. Автокоммит, автотег и публикация всех тегов исключены. +- Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. +- Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к проверкам проекта и CI сохранены; команды определяются документацией потребителя. +- Параметры `conventional-changelog` сверены read-only с README и `src/Changelog.php` установленного инструмента; `gh release create --help` подтверждает `--verify-tag`. Фактические релизные команды не запускались. +- `composer validate --strict` — успешно (`./composer.json is valid`); это проверка из `.github/workflows/ci.yml`. `composer.json` не содержит приватных/VCS-репозиториев: зависимости только PHP и публичный `ramsey/conventional-commits`. +- `git diff --check` — успешно. Относительные ссылки и якоря проверены Python-скриптом: 42 в исходной документации и 42 в установленной копии, ошибок нет. +- `php bin/git-workflow-init /tmp/git-workflow-init.1OVc0M` — 11 документов скопированы в новый временный каталог; `diff -r docs/git-workflow /tmp/git-workflow-init.1OVc0M/docs/git-workflow` — без различий. Проверены `docs/releases/.gitkeep` и запись `git-workflow/` в `docs/.gitignore`. +- Повторный запуск init — 0 скопировано, 11 пропущено; копия по-прежнему совпадает с исходниками. +- Самопроверка полного diff выполнена; уточнены синхронизация через выбранную базу и `--ff-only`, а также порядок patch-релиза для закрытой production line. +- Первоначальное независимое ревью технического писателя одобрило изменения, но не выявило перечисленных ниже смысловых недостатков. Его заключение не используется как подтверждение исправленной редакции; повторная вычитка и исправления выполнены лично, без делегирования, по запросу пользователя. +- Перед публикацией сохранено явное правило `done` до окончательного одобрения PR реализации; отдельный PR постановки не завершает будущую реализацию. +- Открыт PR [#10](https://github.com/prikotov/git-workflow/pull/10) с меткой `pi`; CI `validate` успешен. Задача финализируется в той же ветке до окончательного одобрения; после служебного коммита проверки повторяются. +- Фактические merge, релизы и теги не выполнялись; vendor, код и зависимости не изменялись. + +### Доработка после замечаний пользователя + +Ниже сохранена история промежуточных редакций и ошибок агента. Действующий порядок приведён в разделе «Отдельная ветка каждого выпуска»; прежние правила общей `release/x.y` и её восстановления заменены. Прежние предписания конкретных команд проверок также отменены: актуальная документация отсылает к правилам проекта-потребителя. + +- Задача возвращена в `review` перед исправлениями. Во взаимосвязанных документах явно различены имена рабочих веток, пути файлов и идентификаторы коммитов. +- Сохранён обязательный предрелизный запуск `make tests-e2e`. Убрано добавленное требование полного повторного прогона и отдельного CI только из-за нового идентификатора коммита после слияния. Непроверенные изменения проверяются по правилам проекта. +- Убрано предписание закрывать другую активную релизную ветку ради срочного исправления. Для закрытой ветки текущей рабочей версии не подставляется ветка следующего релиза; выбор целевой ветки согласуется с пользователем. +- План релиза теперь содержит будущие действия и ожидаемые результаты, а не утверждения о ещё не выполненных проверках и выкладке. Фактические результаты записываются в комментариях к PR подготовки релиза. +- Повторно выполнены `composer validate --strict`, `git diff --check`, установка в `/tmp/git-workflow-revision-init.uTaXxW` и повторная установка: 11 документов скопированы, затем 11 пропущены; копия полностью совпадает с исходниками. +- После завершения правок задача снова оформляется в `done` до запроса окончательного одобрения. Текущее состояние автоматических проверок доступно в PR #10; предыдущие результаты CI относятся к предыдущей редакции. + +### Промежуточная редакция источника релиза (заменена) + +Следующие пункты описывают предыдущую редакцию и её проверки, не действующий порядок. Пользователь затем уточнил назначение `release/*`; актуальное решение приведено ниже. + +- Пользователь указал риск выпуска кода, отсутствующего в основной ветке. При исправлении агент ошибочно перенёс финализацию из `release/*` в `task/*`. +- Код, исправления и релизные файлы сначала включаются в `master`/`main` через PR; только затем фиксируется актуальный коммит основной ветки для релизной ветки и тега. Это относится и к обычному повышению `patch`. +- Добавлена проверка принадлежности коммита основной ветке командой `git merge-base --is-ancestor`. Срочное исправление от рабочего тега не смешивается с обычным релизом; для него сохранён обязательный возврат изменений в основную ветку. +- В изолированных временных Git-репозиториях выполнены шесть проверок команд документации: для `master` и `main` допускается коммит основной ветки, отклоняется код только в боковой ветке, сохраняется выбранный коммит при последующем продвижении основной ветки. Все проверки успешны; релизные теги проекта не создавались. +- `composer validate --strict`, проверка ссылок и `git diff --check` повторены успешно. Установка и повторная установка во временный каталог проверены; документы совпадают с исходниками. Обязательный предрелизный `make tests-e2e` в инструкциях сохранён; фактический релиз не выполняется. +- Исправления и повторная вычитка выполнены лично, без делегирования. Задача возвращалась в `review` и снова оформляется в `done` перед окончательным одобрением. Актуальные результаты CI доступны в PR #10. + +### Исправление назначения релизной ветки + +- По указанию пользователя `release/x.y` — рабочая ветка финализации от актуального `master`/`main`, а не цель входящих PR. Убраны запрет коммитов в ней и промежуточная ветка подготовки. +- PR направлен из релизной ветки в основную. Тег обычного релиза ставится после слияния на его результат; содержимое сравнивается с одобренной веткой. Новые коммиты основной ветки не подменяют выбранный результат. +- Документы можно пополнять до релиза в других задачах, включая действия до и после выпуска. Существующий план не перезаписывается шаблоном. +- Срочное исправление и его релизные файлы готовятся в `hotfix/*` от рабочего тега, без входящего PR в `release/*`; возврат в основную ветку обязателен. Предрелизные сквозные тесты и разрешения пользователя сохранены. +- Проверки: `composer validate --strict`, валидация изменённой задачи, `git diff --check`, 27 локальных ссылок и якорей. Установка и повторная установка в изолированный каталог — 11 документов совпадают с исходниками. +- Выполнены 48 проверок в шести изолированных Git-сценариях для `master`/`main` и трёх способов слияния: создание рабочей релизной ветки с ранними документами, коммиты финализации, отказ до включения в основную ветку, проверка результата слияния и более поздних изменений, публикация только выбранного неизменяемого тега. Реальные репозитории при этих испытаниях не сливались и не тегировались. + +### Уточнение базы срочного исправления + +- В шаблоне разделены база рабочей ветки и цель PR; линия версии `x.y` больше не обозначается именем ветки `release/x.y`. Общие проверки документов применяются и к срочным исправлениям. +- Выполнены 14 дополнительных проверок для `master` и `main`: после удаления релизной ветки локально и в удалённом репозитории команда из `branches.md` создаёт `hotfix/*` от тега рабочей версии, сохраняет её документы и исключает невыпущенные изменения основной ветки. Исходный тег не меняется. +- Повторены 48 проверок обычного релиза, проверка Composer, ссылок, задачи и установки документов. Команды документации не изменены. +- Сценарий срочного исправления расширен до 34 проверок: конфликт с ушедшей вперёд основной веткой разрешается после публикации, исправление возвращается в неё вместе с новыми изменениями, оба опубликованных тега сохраняют исходное содержимое. После возврата рабочая ветка удаляется. + +### Восстановление исходного маршрута срочного исправления + +- Исправлена ошибка агента: перед новым тегом обязателен PR `hotfix/*` → `release/x.y` выпущенной линии. Тег отмечает проверенный результат слияния. После выпуска отдельный PR возвращает патч из `release/x.y` в основную ветку. +- Пользователь подтвердил восстановление удалённой ветки выпущенной линии от рабочего тега и её сосуществование с веткой следующего обычного релиза. При конфликте имени или несогласованном составе — остановка, без перезаписи ветки. +- Сохранены порядок обычного релиза, проверки, одобрения, разрешение на выпуск, неизменяемость тегов и обязательный предрелизный `make tests-e2e`. +- Для проверки выбран именно согласованный маршрут: неслитый `hotfix/*` не может стать срочным выпуском; слияние в выпущенную линию предшествует тегу; возврат в основную ветку идёт после выпуска. Прежние 34 проверки прямого выпуска из `hotfix/*` не подтверждают этот маршрут. +- Проверки исправленной редакции: `composer validate --strict`, валидация изменённой задачи и установка/повторная установка 11 документов — успешно. Ссылки и `git diff --check` проверены. Git-моделирование: 394 проверки срочного исправления и 48 проверок неизменённого обычного релиза. Покрыты существующая и удалённая ветки, следующая релизная линия, конфликт имени, разные истории после squash/rebase, запрет выпуска неслитого исправления, проверка состава, возврат с конфликтами после выпуска и сохранность тегов. Это моделирование в изолированных репозиториях, не реальные PR, выпуски или сквозные тесты приложения. + +### Условия запуска сквозных тестов и оформление шаблона + +- Пользователь явно подтвердил новое условие: при срочном исправлении сквозные тесты запускаются только по его запросу. Это заменяет описанное выше обязательное выполнение для всех выпусков; обычный релиз по-прежнему требует `make tests-e2e`. +- Согласованы регламент, чеклисты, шаблон и ссылка на проверки в инструкции выкладки. `make check`, CI, порядок слияния и тегирования не изменены. +- Двоеточия в шаблоне обозначают поля для заполнения. У двух готовых инструкций проверки окружения и миграций они были лишними и удалены. Двоеточия перед вложенными списками и примерами в остальных документах корректны и сохранены. +- Проверки: `composer validate --strict`, валидация задачи, установка и повторная установка 11 документов — успешно. Сравнение с предыдущей редакцией подтвердило неизменность правил обычного релиза и Bash-команд; отдельно проверены условие явного запроса для срочного исправления и сохранность полей шаблона. Повторены 394 проверки Git-модели срочного исправления и 48 проверок обычного релиза. Сквозные тесты приложения не запускались: изменена только документация. + +### Разделение шаблонов плана релиза + +- Пользователь подтвердил два шаблона: `release-plan.template.md` для обычного релиза и `hotfix-release-plan.template.md` для срочного исправления. Из обоих убраны выбор сценария и пункты другого вида выпуска; общие данные о составе, рисках, миграциях и проверках сохранены. +- Обновлены ссылки выбора шаблона в регламенте и перечне артефактов, а также структура пакета в `AGENTS.md`. Заполненный план в обоих случаях остаётся `docs/releases/vX.Y.Z/release-plan.md`. +- Порядок выпуска, источники веток, требования к проверкам и общий регламент не изменены. Скрипт установки не менялся. +- Проверены разделение сценариев, сохранность общих полей, условия сквозных тестов и оба маршрута PR. Установка и повторная установка: 12 документов совпадают с исходниками. При обновлении без `--force` существующие документы сохранены, новый шаблон добавлен; с `--force` обновлены все конвенции, заполненный план релиза не затронут. +- `composer validate --strict`, валидация задачи, ссылки и `git diff --check` — успешно. Повторены 394 проверки Git-модели срочного исправления и 48 проверок обычного релиза. Изменена только документация; тесты приложения не запускались. + +### Подсказки для заполнения полей + +- По замечанию пользователя после двоеточий добавлены 43 подсказки в квадратных скобках: 21 в обычном плане и 22 в срочном. В начале обоих шаблонов указано заменять подсказки данными выпуска по мере подготовки и выполнения плана. +- Проверено отсутствие пустых полей и совпадение подсказок у общих полей. После удаления подсказок и вводной строки оба шаблона полностью совпадают с редакцией `fb2051e`: правила и проверки выпуска не изменены. +- Проверки Composer, задачи, ссылок и форматирования — успешно. Установка и повторная установка: все 12 документов совпадают с исходниками. Тесты приложения не запускались: только документация. + +### Единый формат всех изменяемых значений + +- Исправлена повторная ошибка агента: предыдущая проверка охватывала только пустые поля и пропустила тег, названия веток и другие заменяемые значения. Все 50 изменяемых полей и оба заголовка теперь используют подсказки в квадратных скобках. +- Фиксированные правила — повышение только `patch` для срочного исправления и отказ от отката — сохранены. Разделы проверок до и после выкладки дословно совпадают с `dc1ec8b`; порядок выпуска не менялся. +- Проверены все поля, а не только прежние пустые строки; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование — успешно. Изменена только документация. + +### Удаление избыточной инструкции и уточнение вида выпуска + +- По замечанию пользователя из обоих шаблонов удалена инструкция о замене подсказок. В плане срочного исправления поле заменено на «Тип выпуска: `hotfix`»; вид выпуска больше не обозначается уровнем повышения версии. +- Сравнение с `c8953a0` подтвердило отсутствие других изменений шаблонов. Все 50 изменяемых полей и оба заголовка сохранены; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование проверены успешно. + +### Определение основной ветки + +- В `branches.md` основная ветка обозначена как ветка по умолчанию. Команды обновляют `origin/HEAD`; для переключения получают имя локальной ветки, для слияния и переноса используют ссылку напрямую. Убрана ручная замена `master`/`main`. +- Команды документации проверены в 27 изолированных сценариях: `master`, `main` и имя с вложенным путём; актуальная, отсутствующая и устаревшая ссылка; создание задачи, слияние и перенос. Ещё три проверки подтверждают остановку создания задачи при недоступном репозитории, неопределённой основной ветке и расхождении локальной базы. +- Composer, задача, ссылки и форматирование проверены; установка и повторная установка 12 документов совпадают с исходниками. Правила срочного выпуска и теги не менялись. + +### Отдельная ветка каждого выпуска + +- Пользователь уточнил: сохраняется ветка каждого выпуска, включая каждый патч, а не общая линия `release/x.y`. Исправлены регламент, правила веток и PR, чеклисты и оба шаблона; инструкции TasK согласованы в PR #2899. В `todo-md` правил релизных веток нет, его PR не требует изменений. +- Для исправления `v1.2.0` создаются новые `release/1.2.1` и `hotfix/1.2.1-…` от тега. PR исправления сливается в новую релизную ветку до тега `v1.2.1`. После выпуска PR идёт из неё в основную без временной ветки; адаптация выполняется после выпуска, тег неизменяем. Следующий патч начинается от тега, не от изменённой вершины сохранённой ветки. +- Сохраняются все релизные ветки локально и в `origin`, а также теги. Удаляются только завершённые `task/*` и `hotfix/*`. Ветки предыдущих и параллельно готовящихся выпусков не переиспользуются. При занятом имени или версии — остановка. +- Новая Git-модель: 774 проверки в изолированных локальных репозиториях — 567 срочного выпуска, 108 обычного, 45 сохранности веток и тегов, 45 конфликтов имён, 9 остановки при ошибке подготовки. Девять сценариев охватывают `master`, `main`, `team/main`, merge/squash/rebase первого PR, два последовательных патча и следующий обычный релиз. Проверены команды документации, прямой возврат после выпуска с конфликтами, неизменность старых веток и тегов, база следующего патча, отказ до слияния и при неверном составе. Это не настоящие PR, CI или тесты приложения; прежние 394 проверки общей линии не подтверждают новую модель. +- При проверке обнаружено: пример создания `hotfix/*` продолжал работу после ошибки `git fetch`. Ошибка воспроизведена отдельным тестом; команды связаны через `&&`. Теперь недоступный `origin`, отсутствующий рабочий тег и занятое имя останавливают создание без изменения ветки и тегов. +- Composer, валидация задачи, ссылки и форматирование проверены. Все 50 изменяемых полей шаблонов сохранены, условия E2E не изменены. Установка и повторная установка 12 документов, сохранение пользовательских файлов без `--force` и обновление конвенций с `--force` без изменения заполненного плана — успешно. Повторены 30 проверок `origin/HEAD`; обычный релиз и его шаблон теперь также используют основную ветку по умолчанию. +- Автоматическое удаление исходной ветки после слияния отключено в GitHub у `git-workflow` и TasK; настройки не менялись. Ограничение CI пакета по целевым веткам сохраняется и указано ниже. + +## 7. Риски и зависимости (Risks and Dependencies) +- Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. +- CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. +- Изменяется предписанный релизный процесс; реальные слияния, теги и выпуски не разрешены. + +## 8. Источники (Sources) +- [Ветки](../../docs/git-workflow/branches.md). +- [Коммиты](../../docs/git-workflow/commits.md). +- [Запросы на слияние](../../docs/git-workflow/pull-request.md). +- [Релизы](../../docs/git-workflow/release.md). +- [Связанные проектные уточнения TasK](https://github.com/prikotov/TasK/pull/2899). + +## 9. Комментарии (Comments) +Постановка пользователя: учесть принадлежность документов другим проектам в `~/MyProjects`, устранить найденные противоречия в исходниках и предоставить готовые PR. План подтверждён сообщением «делай». + +## История изменений (Change History) +| Дата | Автор (роль) | Изменение | +| :--- | :--- | :--- | +| 2026-09-11 03:45:03 (1789098303) | Технический писатель (pi) | Создание задачи по согласованному плану | +| 2026-09-11 | Лид (pi) | Реализация и независимое ревью завершены; PR #10 опубликован, CI успешен, задача подготовлена к приёмке | +| 2026-09-11 | Технический писатель (pi) | Повторная личная вычитка по замечаниям пользователя: исправлены терминология, проверки релиза, сценарий срочного исправления и шаблон плана; проверки повторены | +| 2026-09-11 | Технический писатель (pi) | По уточнению пользователя обычный релиз переведён на источник master/main: подготовка через PR в основную ветку, фиксация её коммита, отдельный сценарий срочного исправления | +| 2026-09-11 | Технический писатель (pi) | По запросу пользователя убраны пояснение «имя ветки, а не путь», повторы и многословные оговорки в инструкциях, чеклистах и шаблоне; правила сохранены | +| 2026-09-11 | Технический писатель (pi) | Исправлена ошибочная модель агента: финализация и коммиты в release/*, PR из неё в master/main; документы накапливаются заранее в обычных задачах | +| 2026-09-11 | Технический писатель (pi) | Убраны «задолго до выпуска», повторы и избыточные пояснения; правила и команды сохранены | +| 2026-09-11 | Технический писатель (pi) | Описательные формулировки заменены действиями; уточнены объекты проверок, убран повтор процесса слияния из правил релизных документов | +| 2026-09-11 | Технический писатель (pi) | Из releases/index.md удалён дубль правила записи результатов в комментариях PR | +| 2026-09-11 | Технический писатель (pi) | Из releases/index.md удалено избыточное указание о каталоге для срочных исправлений и патч-релизов | +| 2026-09-12 | Технический писатель (pi) | В шаблоне разделены база рабочей ветки и цель PR, линия версии отделена от имени ветки; удалён дубль отчётности. База срочного исправления — тег текущей рабочей версии; общие проверки релизных документов больше не привязаны только к release/x.y | +| 2026-09-12 | Технический писатель (pi) | В шаблоне и регламенте различены PR подготовки обычного релиза и PR возврата срочного исправления после выпуска; добавлены проверки коммита срочного выпуска и возврата исправления | +| 2026-09-12 | Технический писатель (pi) | Восстановлен ошибочно изменённый агентом маршрут срочного исправления через PR в выпущенную линию до тега; подтверждено исключение для её сосуществования с подготовкой следующего релиза | +| 2026-09-12 | Технический писатель (pi) | По замечаниям пользователя удалено поле «Линия релиза»; поле ссылки на PR названо «PR включения срочного исправления в основную ветку (после выпуска)» | +| 2026-09-12 | Технический писатель (pi) | По подтверждённому запросу сквозные тесты срочного исправления запускаются только по запросу пользователя; для обычного релиза обязательность сохранена. Исправлены два лишних двоеточия у готовых инструкций шаблона | +| 2026-09-12 | Технический писатель (pi) | Разделены шаблоны обычного релиза и срочного исправления; обновлены ссылки и структура пакета без изменения регламента выпуска | +| 2026-09-12 | Технический писатель (pi) | Пустые поля обоих шаблонов дополнены предметными подсказками; добавлена инструкция по их замене данными выпуска | +| 2026-09-12 | Технический писатель (pi) | Исправлена неполнота предыдущей правки: все изменяемые поля, включая тег, ветки и заголовки, приведены к единому формату подсказок | +| 2026-09-12 | Технический писатель (pi) | Удалена избыточная инструкция по заполнению; в плане срочного исправления указан тип выпуска hotfix вместо уровня повышения версии | +| 2026-09-12 | Технический писатель (pi) | В branches.md ручная подстановка master/main заменена определением основной ветки через origin/HEAD; команды проверены в изолированных репозиториях | +| 2026-09-12 | Технический писатель (pi) | По уточнению пользователя каждый выпуск получает отдельную сохраняемую release/x.y.z; срочный PR идёт в новую ветку, после выпуска — из неё в основную без временной ветки. Выполнены 774 проверки новой Git-модели | +| 2026-09-13 | Технический писатель (pi) | В срочном плане обоснование версии заменено на причину исправления с описанием ошибки: hotfix сохраняет совместимость. Проверены точечность правки, Composer, задача, ссылки и установка документов | +| 2026-09-13 | Технический писатель (pi) | По запросу пользователя из срочного плана удалены «Плановая дата deploy» и «Вне состава релиза»; обычный шаблон не изменён. Проверены точечность удаления, Composer, задача, ссылки и установка документов | +| 2026-09-13 | Технический писатель (pi) | Добавлен glossary.md: 26 терминов в формате «русский (English) — пояснение» со стабильными якорями. Словарь связан с оглавлением, README и регламентами; выпуск отделён от выкладки. Проверены формат и отображение, ссылки, установка и обновление 13 документов, Composer и задача | +| 2026-09-13 | Технический писатель (pi) | В срочном шаблоне явно указано: PR исправления слить до создания тега, PR в основную ветку открыть после публикации GitHub Release. Согласован пункт проверки до создания тега. Проверены точечность трёх изменений, неизменность обычного шаблона, Composer, ссылки, задача и установка 13 документов | +| 2026-09-13 | Технический писатель (pi) | Упрощены риски срочного шаблона: удалены отдельные поля окна несовместимости и замечаний по обратной совместимости; риски исправления и выкладки остаются в общем поле. Проверка миграций сформулирована через безопасный порядок обновления кода и данных. Проверены точечность правок, Composer, ссылки, задача и установка 13 документов | +| 2026-09-13 | Технический писатель (pi) | В срочном шаблоне ошибочный выбор между hotfix и patch release заменён конкретными действиями при проблеме; обе подсказки ответственного уточнены до «имя или ссылка на профиль роли». Проверены точечность трёх правок, неизменность обычного шаблона, Composer, ссылки, задача и установка 13 документов | +| 2026-09-13 | Технический писатель (pi) | Обычный шаблон приведён к стилю срочного: явное слияние до создания тега, профили ролей, общие риски и действия при проблеме; удалены дублирующие поля. Сохранены выбор версии, плановая дата выкладки, описание несовместимых изменений и обязательные E2E. Срочный шаблон не менялся. Проверены точный состав правок, общие разделы и различия сценариев, Composer, ссылки, задача, установка и обновление 13 документов | +| 2026-09-13 | Технический писатель (pi) | В раздел Release branch файла branches.md возвращены команды создания и публикации новой релизной ветки: от основной для обычного релиза и от рабочего тега для срочного исправления. Примеры совпадают с release.md; явно сохранена проверка свободных имён. На восстановленных командах повторены 774 проверки Git-модели, дополнительно 30 проверок origin/HEAD, Composer, ссылки, задача и установка документов | +| 2026-09-13 | Технический писатель (pi) | Синхронизация перенесена в собственные подразделы Task branch, Release branch и Hotfix branch; общий раздел переименован в «Создание и синхронизация веток». Сохранены все прежние команды, отдельно описаны ограничения срочной релизной ветки, добавлены примеры синхронизации hotfix только с его целевой release-веткой. Проверены структура, шесть сценариев новых команд, 774 проверки Git-модели, 30 проверок origin/HEAD, Composer, ссылки, задача и установка документов | +| 2026-09-13 | Технический писатель (pi) | Под заголовками Task branch, Release branch и Hotfix branch восстановлены короткие пояснения назначения перед подразделом «Создание». Проверено, что изменились только три пояснения; команды и правила сохранены. Composer, ссылки, задача, проверки структуры и синхронизации, установка документов — успешно | +| 2026-09-13 | Технический писатель (pi) | По согласованию с пользователем для синхронизации закреплён только merge: удалены три варианта rebase и предложение выбирать способ. Способы интеграции PR на GitHub не менялись. Проверены точечность правок, сохранение существующих коммитов, три сценария hotfix-синхронизации, 30 проверок origin/HEAD, 774 проверки Git-модели, Composer, ссылки, задача и установка документов | +| 2026-09-13 | Технический писатель (pi) | В Release branch оставлен только обычный релиз. Весь срочный сценарий перенесён в Hotfix branch: создание целевой release-ветки от рабочего тега, ограничения синхронизации и отдельный возврат после публикации GitHub Release. Порядок работы сохранён. Проверены разделение сценариев, сохранность команд, синхронизация и возврат без изменения тегов, 774 проверки Git-модели, 30 проверок origin/HEAD, Composer, ссылки, задача и установка документов | +| 2026-09-13 | Технический писатель (pi) | Именование с примерами и завершение перенесены внутрь Task branch, Release branch и Hotfix branch; общий раздел назван «Работа с ветками». Каждая секция описывает свой полный цикл, включая сохранение релизных веток и тегов. Проверены порядок подразделов, неизменность всех команд, 774 проверки Git-модели, 30 проверок origin/HEAD, синхронизация и возврат, Composer, ссылки, задача и установка документов | +| 2026-09-14 | Технический писатель (pi) | В branches.md и release.md добавлены короткие комментарии к обновлению origin/HEAD, чтению имени основной ветки и удалению префикса origin/ при переключении. Проверено, что добавлены только 13 комментариев; команды и порядок не менялись. Синтаксис Bash, 774 проверки Git-модели, 30 проверок origin/HEAD, синхронизация и возврат, Composer, ссылки, задача и установка документов — успешно | +| 2026-09-14 | Технический писатель (pi) | Из определения выкладки в deploy.md удалена ссылка на словарь; само определение и правила не менялись. Проверены точечность правки, Composer, ссылки, задача и установка документов | +| 2026-09-14 | Технический писатель (pi) | Из deploy.md удалена дублирующая строка «Выкладка из вершины ветки запрещена»; требование устанавливать версию по конкретному тегу релиза сохранено. Проверены точечность удаления, Composer, ссылки, задача и установка документов | +| 2026-09-14 | Технический писатель (pi) | В рекомендуемом потоке deploy.md выделено требование выполнять подготовительные и завершающие действия из документации конкретной версии на указанных в ней этапах; отмечено пополнение инструкций при выполнении задач. Проверены точечность дополнения, сохранение порядка и разрешений, Composer, ссылки, задача и установка документов | +| 2026-09-14 | Технический писатель (pi) | Из общих правил, чеклистов и шаблонов убраны предположения о командах проверок потребителя. Набор проверок и запуск определяет документация проекта; при отсутствии инструкций нужен вопрос пользователю. Условия сквозных тестов и CI сохранены. Проверены отсутствие make-команд в распространяемых документах, сохранение сценариев, 774 проверки Git-модели, Composer, ссылки, задача и установка документов |