From 9db50cad4c4715423201675c662feb05718fae24 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Fri, 11 Sep 2026 10:59:48 +0700 Subject: [PATCH 01/40] =?UTF-8?q?docs(workflow):=20align=20branch=20and=20?= =?UTF-8?q?release=20instructions=20/=20=D1=81=D0=BE=D0=B3=D0=BB=D0=B0?= =?UTF-8?q?=D1=81=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D0=B8=D0=BD=D1=81=D1=82?= =?UTF-8?q?=D1=80=D1=83=D0=BA=D1=86=D0=B8=D0=B8=20=D0=B2=D0=B5=D1=82=D0=BE?= =?UTF-8?q?=D0=BA=20=D0=B8=20=D1=80=D0=B5=D0=BB=D0=B8=D0=B7=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 36 ++++-- docs/git-workflow/commits.md | 15 ++- docs/git-workflow/deploy.md | 4 +- docs/git-workflow/pull-request.md | 45 ++++--- docs/git-workflow/release-checklists.md | 18 ++- docs/git-workflow/release.md | 116 +++++++++--------- docs/git-workflow/releases/index.md | 3 +- .../templates/release-plan.template.md | 7 +- ...K-docs-align-workflow-instructions.todo.md | 113 +++++++++++++++++ 9 files changed, 251 insertions(+), 106 deletions(-) create mode 100644 todo/TASK-docs-align-workflow-instructions.todo.md diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 3daa0a0..d5af766 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -47,11 +47,19 @@ package: prikotov/git-workflow ### Task branch -Используется для обычной разработки и документации. +Для обычной разработки и документации база и цель PR — `master`. ```bash git switch master -git pull origin master +git pull --ff-only origin master +git switch -c task/ +``` + +Для стабилизации и подготовки релизных файлов база и цель PR — активная `release/x.y`: + +```bash +git switch release/x.y +git pull --ff-only origin release/x.y git switch -c task/ ``` @@ -61,7 +69,7 @@ git switch -c task/ ```bash git switch master -git pull origin master +git pull --ff-only origin master git switch -c release/x.y git push -u origin release/x.y ``` @@ -84,21 +92,33 @@ git switch -c hotfix/x.y.z- vX.Y.Z ## Синхронизация -- `task/*` синхронизируется с `master`. -- `release/*` синхронизируется только с собственной release line; новые feature commits из `master` туда не подтягиваются автоматически. +- `task/*` синхронизируется со своей базой: `master` для обычной разработки, активной `release/x.y` для стабилизации и подготовки релиза. +- База синхронизации совпадает с целью PR; не подтягивай `master` в рабочую ветку релиза. +- Локальная `release/*` обновляется только из одноимённой ветки `origin` через `--ff-only`; изменения в неё поступают через PR, новые feature commits из `master` не подтягиваются. - `hotfix/*` после merge должен присутствовать в active `release/x.y` и в `master`. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. +В рабочей ветке выбери базу и получи её актуальное состояние: + ```bash +base=master # Для стабилизации и подготовки релиза: base=release/x.y git fetch origin -git merge origin/master ``` +Затем используй **один** согласованный способ — merge: + ```bash -git fetch origin -git rebase origin/master +git merge "origin/$base" +``` + +Или rebase: + +```bash +git rebase "origin/$base" ``` +Синхронизацию заверши до окончательного одобрения PR. Если после одобрения нужны изменения — повтори проверки и запроси новое одобрение по [правилам PR](pull-request.md#подготовка-pr). + ## Завершение - После merge PR рабочую ветку нужно удалить локально и в `origin`. diff --git a/docs/git-workflow/commits.md b/docs/git-workflow/commits.md index 0093614..8570ecc 100644 --- a/docs/git-workflow/commits.md +++ b/docs/git-workflow/commits.md @@ -80,7 +80,8 @@ Scope указывает на область изменения, в качест - Не смешивай в одном коммите разные типы изменений. - Не смешивай в одном коммите поведение и форматирование. - Не смешивай `move/rename` и `refactor/behavior change` в одном коммите. -- Используй `git commit -m ...` без генераторов. +- Используй `git commit -m ...` без генераторов, в том числе для релизных коммитов. +- Этот документ — единый источник правил подготовки сообщений; интерактивный помощник не требуется. ## Примеры @@ -156,13 +157,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 +176,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..b5102c8 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,8 +28,8 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Подготовить и стабилизировать active `release/x.y`. -2. Создать и запушить tag `vX.Y.Z`. +1. Подготовить и стабилизировать active `release/x.y`; релизные файлы включить через одобренный PR из `task/*`. +2. Проверить слитый коммит `release/x.y`, создать на нём неизменяемый tag `vX.Y.Z` и опубликовать только этот тег по [процессу релиза](release.md#выпуск-релиза). 3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. 4. Провести post-check: основные user-flow, логи, метрики. 5. При проблеме остановить rollout и выпустить hotfix или patch release. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index f3970ed..bd85487 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -16,7 +16,7 @@ package: prikotov/git-workflow ## Правила -- Запрещены прямые правки в `master`. +- Запрещены прямые правки в `master` и `release/*`. - Одна задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. @@ -39,24 +39,28 @@ package: prikotov/git-workflow ## Выбор base branch - `task/*` для обычной разработки → `master`. -- Stabilization fixes для текущего релиза → активная `release/x.y`. +- `task/*` для стабилизации и подготовки релизных файлов создаётся от активной `release/x.y` → PR в эту же `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. +- Если production line уже закрыта, восстанови `release/x.y` от production tag по [правилам релиза](release.md#hotfix-и-patch-release) и направь hotfix PR в неё; merge-back в `master` — отдельным PR сразу после patch release. + +## Обязательные проверки + +- По умолчанию перед PR обязателен успешный `make check`, в том числе для `docs-only` и служебных изменений. +- Пропуск или замена проверки допустимы только по явной политике проекта-потребителя (например, в его `AGENTS.md`): должны быть указаны применимые категории изменений и необходимые проверки вместо пропущенной. +- При отсутствии такого исключения проверки обязательны. Отсутствующая команда или сбой окружения не считаются успешной проверкой и не разрешают пропуск. +- В PR укажи выполненные команды, результаты и ссылку на применимое проектное исключение, если оно использовано. +- Исключение для `make check` не отменяет остальные обязательные проверки и 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 с явной базой: `gh pr create --base --head "$(git branch --show-current)"`; `` — `master` или выбранная `release/x.y`. - Тело PR передавай через `gh pr create --body-file`. - Предпочитай `--body-file -` (stdin) или файл в `tmp/`. -- После создания PR обнови поле `PR` в задаче (`todo/...`) ссылкой или номером созданного PR. +- Связь задачи с PR и переходы статусов веди по установленным в проекте правилам `todo-md`. Формат полей и механика задач не определяются этим пакетом. ## Оформление PR @@ -67,7 +71,7 @@ package: prikotov/git-workflow - нужен ли merge-back в `master`; - какие изменения сознательно **не** входят в этот релиз. - Описание PR включает: - - если задачи в `todo/` ещё нет — оформи её по правилам: [todo/AGENTS.md](../../todo/AGENTS.md); + - если проект использует `todo-md` и задачи ещё нет — оформи её по установленным в проекте правилам `todo-md`; - постановку задачи из prompt; - постановку задачи из `todo/.todo.md` (если есть); - цель и причину изменений; @@ -91,25 +95,28 @@ package: prikotov/git-workflow ## Подготовка PR -- Дождись зелёного CI на созданном PR. -- Переведи задачу в `done` по правилам проекта и запушь в ту же ветку. -- Только после перевода задачи в `done` запроси апрув (approve) у пользователя. -- После апрува в PR-ветку не пушится ничего — только `gh pr merge`. +- Заверши все изменения в PR-ветке до запроса окончательного одобрения (approve), включая релизные файлы и служебные обновления задачи по правилам `todo-md` проекта. +- Если PR завершает реализацию задачи, переведи её в `done` до окончательного одобрения и отправь изменения в ту же ветку. Формат полей, перенос файла и обновление ссылок определяет `todo-md`; момент завершения относительно одобрения определяет этот Git-процесс. +- PR только с постановкой не завершает реализацию поставленной задачи: она остаётся в `todo` или `backlog` по правилам проекта. Если работа над постановкой ведётся отдельной задачей, заверши только её. +- После последнего push дождись зелёного CI и выполни обязательные проверки окончательного состояния PR. +- Запроси одобрение пользователя именно на это состояние PR. +- После одобрения не добавляй коммиты и не пушь в 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`. +- Возврат изменений (merge-back) из `release/x.y` в `master`, в том числе hotfix, выполняй отдельным PR из рабочей ветки. ## После merge -- После merge PR в `master` переключись на `master` и обнови его: `git pull origin master`. +- После merge PR в `master` переключись на `master` и обнови его: `git pull --ff-only origin master`. - После merge PR в `release/x.y` переключись на эту release line только если продолжается стабилизация; иначе вернись в `master`. - Удали рабочую ветку локально и в `origin`. - Проверь, что рабочее дерево чистое: `git status`. diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 6eb3d85..f59f26d 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -12,10 +12,14 @@ package: prikotov/git-workflow - Следующая версия выбрана по [правилам 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` и описание релиза подготовлены. +- Для новой minor/major линии `release/x.y` создана от согласованного коммита `master`; patch использует текущую production line (при необходимости восстановленную от production tag). Активная линия только одна. +- Рабочие `task/*` для стабилизации и релизных файлов созданы от `release/x.y`, синхронизируются с ней и целятся PR в неё. +- `CHANGELOG.md`, файлы версий и заполненный `docs/releases/vX.Y.Z/release-plan.md` подготовлены в рабочей ветке без автоматического коммита и тега. +- Все правки, включая служебные обновления задачи, включены до окончательных проверок и одобрения PR. +- Для релиза выполнены `make check` и `make tests-e2e`; исключения допустимы только по [явной политике потребителя](pull-request.md#обязательные-проверки). +- Окончательное состояние PR одобрено пользователем, CI зелёный, merge в `release/x.y` подтверждён и выполнен через GitHub. +- Полный SHA результата слияния зафиксирован; состав, релизные файлы, обязательные проверки и CI проверены на этом SHA. +- После разрешения на выпуск неизменяемый тег создан только на проверенном слитом SHA; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления @@ -23,12 +27,14 @@ package: prikotov/git-workflow - `hotfix/x.y.z-` создан от тега production, а не от `master`. - Объём срочного исправления минимален и не тянет несвязанные изменения. - Зафиксирован план возврата изменений в активную `release/x.y` и `master`. +- Hotfix проходит PR в `release/x.y`; если production line закрыта, она восстановлена от production tag по [правилам релиза](release.md#hotfix-и-patch-release). - Проверки для срочного исправления пройдены до выпуска патч-релиза. +- Релизные файлы проходят отдельный PR из `task/*` от `release/x.y`; тег создаётся только после проверки результата слияния, как в чеклисте подготовки релиза. ## Чеклист выкладки -- Выбран тег релиза `vX.Y.Z` для выкладки. -- Создан и заполнен `docs/releases/vX.Y.Z/release-plan.md`. +- Выбран опубликованный неизменяемый тег релиза `vX.Y.Z` на проверенном слитом коммите `release/x.y`. +- Заполненный `docs/releases/vX.Y.Z/release-plan.md` уже включён в этот тег через PR. - Web и Workers будут выкачены на один и тот же тег. - В `release-plan.md` зафиксированы миграции, порядок их применения и риск окна несовместимости. - В `release-plan.md` зафиксирован план исправления без отката. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 9f5d589..151a733 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,13 +4,14 @@ 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` как 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, безопасные мелкие правки. +- В `release/x.y` допускаются только stabilizing changes: bugfix, release docs, безопасные мелкие правки — через PR из рабочих веток. +- Прямые коммиты в `master` и `release/*` запрещены; релизные файлы готовятся в `task/*` от активной `release/x.y`. - Production всегда разворачивается по **конкретному tag**, а не по branch head. - Одновременно поддерживается только одна active `release/x.y`. @@ -31,30 +32,24 @@ 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`. Выбранную версию явно передавайте генератору; его автоматическое повышение не заменяет эти правила, особенно для `0.x`. - `patch` сохраняет текущую release line. - `minor` и `major` открывают новую `release/x.y`. ## Подготовка коммитов -Используйте интерактивный помощник: +Сообщения готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. Это относится и к релизным коммитам; обязательного помощника нет. ```bash -make prepare-commit -``` - -Если helper падает, сформируйте заголовок вручную по 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 @@ -62,7 +57,7 @@ git commit -m "type(scope): description" ```bash git switch master -git pull origin master +git pull --ff-only origin master git switch -c release/x.y git push -u origin release/x.y ``` @@ -74,13 +69,13 @@ git push -u origin release/x.y ## План релиза -Для каждого production release перед deploy создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. +Для каждого production release в рабочей ветке подготовки, до одобрения PR и создания тега, создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. - место хранения: `docs/releases/`; - шаблон: [release-plan.template.md](./templates/release-plan.template.md). - без заполненного `release-plan.md` deploy не начинается. -Базовое создание документа после определения тега релиза: +В `task/*` от активной `release/x.y`, после выбора версии (тег ещё не создан): ```bash mkdir -p docs/releases/vX.Y.Z @@ -96,74 +91,75 @@ cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/rel ## Работа с CHANGELOG -Для предпросмотра изменений: +Генерируйте файлы только в рабочей ветке подготовки релиза. Если проект использует `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: они тоже не должны создавать коммиты, теги или выполнять публикацию. +- Команда записывает файлы, это не dry run. Проверьте весь diff: кроме `CHANGELOG.md` могут измениться файлы версий (`composer.json`, `package.json` и другие по конфигурации). +- Если генератор не установлен, подготовьте файлы вручную по тем же правилам. Этот пакет не поставляет генератор или цели `make release-*`. +- Не запускайте обёртки `make release`, `make release-*` или `make changelog`, пока не проверены их действия. Автоматический релизный коммит/тег не входит в этот процесс. + `CHANGELOG.md` должен оставаться коротким: - заголовок релиза; - compare link; -- одна короткая summary-строка. +- одна короткая summary-строка; +- явное указание несовместимости, если она есть, включая версии `0.x`. Подробные notes публикуются в GitHub Release. ## Выпуск релиза -Перед релизом: - -```bash -make check -make tests-e2e -``` - -Релиз выполняется **на active `release/x.y`**, а не на `master`. +### 1. Подготовка файлов через PR -Вариант A — patch по умолчанию: +После стабилизации создайте рабочую ветку от активной линии: ```bash -make release +git switch release/x.y +git pull --ff-only origin release/x.y +git switch -c task/prepare-release-x-y-z ``` -Вариант B — явный тип: +1. Выберите версию по SemVer, подготовьте `CHANGELOG.md`, файлы версий и `docs/releases/vX.Y.Z/release-plan.md` в этой ветке. +2. Проверьте diff и создайте коммит вручную по [commits.md](commits.md). +3. Откройте PR из `task/*` в `release/x.y` по [правилам PR](pull-request.md). Не синхронизируйте эту рабочую ветку с `master`. +4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Для релиза обязательны `make check` и `make tests-e2e`; исключения или замены допустимы только по [явной политике потребителя](pull-request.md#обязательные-проверки). +5. Дождитесь зелёного CI, одобрения окончательного состояния PR и подтверждения merge пользователем; выполните merge через GitHub. После одобрения никаких новых коммитов без повторных проверок и нового одобрения. -```bash -make release-patch -make release-minor -make release-major -``` +### 2. Проверка слитого коммита и создание тега -Что делает release команда: -- обновляет `CHANGELOG.md`; -- определяет или принимает версию; -- делает release commit; -- создаёт git tag `vX.Y.Z`. +- Зафиксируйте полный SHA коммита, полученного после merge PR в `release/x.y` (при squash это новый SHA), а не SHA рабочей ветки. +- Получите актуальную целевую ветку и убедитесь, что выбранный SHA принадлежит ей. Проверьте состав релиза и все релизные файлы на этом SHA. +- Проведите обязательные релизные проверки и дождитесь зелёного CI **именно для этого слитого SHA**. Проверки PR до merge не заменяют проверку результата слияния. +- Если нужны исправления — новый `task/*` от `release/x.y`, новый PR, проверки и одобрение; тег пока не создавайте. +- Если линия сдвинулась, не подменяйте проверенный SHA текущим head: заново согласуйте состав и проверьте выбранный коммит. -После генерации: -1. проверьте `CHANGELOG.md`; -2. создайте и заполните `docs/releases/vX.Y.Z/release-plan.md`; -3. если блок слишком длинный, вынесите подробности в GitHub Release notes; -4. запушьте release branch и tags: +Только после этих проверок и разрешения на выпуск создайте тег на зафиксированном SHA. В примере замените `VERIFIED_MERGED_SHA` полным проверенным SHA, а `X.Y.Z` — выбранной версией: ```bash -git push origin release/x.y -git push origin --tags +release_commit=VERIFIED_MERGED_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 ``` -5. создайте GitHub Release: +- Публикуется только конкретный тег, не все локальные теги; `git push --tags` запрещён. +- Тег production неизменяем: не перемещайте, не перезаписывайте и не публикуйте его с `--force`. +- На защищённой ветке не создаётся дополнительный релизный коммит; генератор после merge не запускается. -```bash -gh release create vX.Y.Z --notes-file tmp/release-vX.Y.Z.md -``` +### 3. GitHub Release -или +Убедитесь, что опубликованный тег указывает на проверенный SHA. Создайте GitHub Release только для уже существующего удалённого тега: ```bash -gh release create vX.Y.Z --generate-notes +gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ``` +Или используйте `--generate-notes` вместо `--notes-file`. Подробные notes подготовьте до публикации; `--verify-tag` не позволяет неявно создать отсутствующий тег. Деплой выполняется только по этому фиксированному тегу. + ## Hotfix и patch release Срочный hotfix не делается от `master`. @@ -172,11 +168,11 @@ gh release create vX.Y.Z --generate-notes 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`. +4. влить hotfix через одобренный PR в active `release/x.y`; +5. подготовить patch release `vX.Y.(Z+1)` в `task/*` от этой линии и выпустить по описанному выше процессу PR → проверка слитого SHA → конкретный тег; +6. выполнить merge-back hotfix changes в `master` отдельным PR из рабочей ветки. -Если active `release/x.y` уже закрыта, hotfix всё равно стартует от production tag, а merge-back в `master` делается отдельным PR сразу после patch release. +Если production line уже закрыта, восстановите `release/x.y` от текущего production tag и направьте hotfix PR в неё. При наличии другой активной линии сначала согласуйте её закрытие: две активные линии запрещены. Далее действует тот же порядок подготовки файлов через PR и тега после проверки слитого коммита; merge-back в `master` — отдельным PR сразу после patch release. ## Recovery Policy diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 901132d..aeaf5ad 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -13,7 +13,8 @@ package: prikotov/git-workflow ## Правила -- Для каждого production релиза перед deploy создаётся каталог `docs/releases/vX.Y.Z/`. +- Для каждого production релиза каталог `docs/releases/vX.Y.Z/` и его файлы готовятся в `task/*` от активной `release/x.y` до окончательного одобрения PR. +- Артефакты включаются в `release/x.y` через PR до создания тега на проверенном слитом коммите: [процесс релиза](../release.md#выпуск-релиза). - Минимально обязательный файл в каталоге релиза: `release-plan.md`. - `release-plan.md` фиксирует состав релиза, риски, миграции, порядок deploy, post-check и план действий через hotfix или patch release. - Для `hotfix` и `patch release` создаётся отдельный каталог по новому тегу релиза. diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 2791fc9..7d1e72a 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -6,7 +6,8 @@ - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: - Линия релиза: `release/x.y` -- Исходная ветка: +- Рабочая ветка подготовки: `task/…` от `release/x.y` +- PR подготовки релиза в `release/x.y`: - Ответственный: - Плановая дата deploy: @@ -31,7 +32,9 @@ ## Проверки перед deploy -- Тег релиза запушен в `origin` +- Этот план и остальные релизные файлы включены через PR до создания тега +- Окончательное состояние PR одобрено; обязательные проверки и CI слитого коммита `release/x.y` успешны +- Тег релиза создан на этом проверенном коммите; в `origin` опубликован только конкретный тег - Подготовлены обязательные изменения в env - В документе зафиксированы миграции, порядок их применения и риск окна несовместимости - Подготовлены команды health-check diff --git a/todo/TASK-docs-align-workflow-instructions.todo.md b/todo/TASK-docs-align-workflow-instructions.todo.md new file mode 100644 index 0000000..a8bf599 --- /dev/null +++ b/todo/TASK-docs-align-workflow-instructions.todo.md @@ -0,0 +1,113 @@ +--- +type: docs +created: 2026-09-11 03:45:03 (1789098303) +due: +started: 2026-09-11 03:46:53 (1789098413) +completed: +cancelled: +value: V2 +complexity: C2 +priority: P1 +cost_plan: +cost_fact: +depends_on: +epic: +author: Технический писатель (pi) +assignee: Технический писатель (pi) +branch: task/align-workflow-instructions +pr: +status: in_progress +--- + +# 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` как базу и цель PR; синхронизировать с выбранной базой. +- [x] Сохранить запрет прямых коммитов в `master` и `release/*`; подготовку релизных файлов выполнять в рабочей ветке через PR. +- [x] Создавать и публиковать конкретный релизный тег только на проверенном слитом коммите целевой ветки; не отправлять все локальные теги. +- [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. +- [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. +- [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. +- [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. +### ⚫ Won't Have (Не будем делать) +- Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. +- Массово переписывать документацию вне выявленных противоречий. + +## 4. План реализации (Implementation Plan) +1. [x] Сверить документы пакета и реальные параметры упоминаемых инструментов. +2. [x] Точечно согласовать ветки, подготовку коммитов, проверки и релиз через PR. +3. [x] Проверить ссылки, выполнить `composer validate --strict` и проверку установки документации во временный каталог. +4. [x] Провести самопроверку и независимое ревью, устранить замечания. +5. [ ] Создать PR с меткой `pi`, заполнить ссылку, дождаться CI и подготовить задачу к приёмке. + +## 5. Критерии приёмки (Definition of Done) +- [x] Все обязательные требования выполнены; инструкции не требуют прямой записи в целевые ветки. +- [x] Проверки Composer и документации успешны; независимое ревью не содержит блокирующих замечаний. +- [ ] PR открыт, задача связана с ним и готова к приёмке; версии и теги не выпускались. + +## 6. Самопроверка (Verification) +```bash +composer validate --strict +git diff --check +``` +Дополнительно: установка документации через `bin/git-workflow-init` в отдельный временный каталог и проверка новых относительных ссылок. CI пакета выполняет `composer validate --strict`. Проверить отсутствие приватных зависимостей в `composer.json`. + +### Результат выполнения + +- Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. +- Релизные файлы готовятся в `task/*` от `release/x.y`, проходят PR и окончательное одобрение; конкретный неизменяемый тег создаётся только на проверенном слитом SHA. Автокоммит, автотег и публикация всех тегов исключены. +- Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. +- Параметры `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. +- Независимое ревью технического писателя: одобрено, блокирующих замечаний нет; повторно проверены параметры генератора, 46 локальных ссылок и якорей, `composer validate --strict` и `git diff --check`. +- Перед публикацией сохранено явное правило `done` до окончательного одобрения PR реализации; отдельный PR постановки не завершает будущую реализацию. +- Публикация PR и удалённый CI — следующий шаг. Фактические merge, релизы и теги не выполнялись; vendor, код и зависимости не изменялись. + +## 7. Риски и зависимости (Risks and Dependencies) +- Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. +- Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через 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) | Создание задачи по согласованному плану | From a48b2bda084fa2bd6ee3f88da38c03f9d25f7990 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Fri, 11 Sep 2026 11:02:21 +0700 Subject: [PATCH 02/40] =?UTF-8?q?docs(tasks):=20complete=20workflow=20inst?= =?UTF-8?q?ructions=20task=20/=20=D0=B7=D0=B0=D0=B2=D0=B5=D1=80=D1=88?= =?UTF-8?q?=D0=B8=D1=82=D1=8C=20=D0=B7=D0=B0=D0=B4=D0=B0=D1=87=D1=83=20?= =?UTF-8?q?=D1=81=D0=BE=D0=B3=D0=BB=D0=B0=D1=81=D0=BE=D0=B2=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=86?= =?UTF-8?q?=D0=B8=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...K-docs-align-workflow-instructions.todo.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) rename todo/{ => done}/TASK-docs-align-workflow-instructions.todo.md (91%) diff --git a/todo/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md similarity index 91% rename from todo/TASK-docs-align-workflow-instructions.todo.md rename to todo/done/TASK-docs-align-workflow-instructions.todo.md index a8bf599..55c156b 100644 --- a/todo/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: +completed: 2026-09-11 04:02:03 (1789099323) cancelled: value: V2 complexity: C2 @@ -15,8 +15,8 @@ epic: author: Технический писатель (pi) assignee: Технический писатель (pi) branch: task/align-workflow-instructions -pr: -status: in_progress +pr: https://github.com/prikotov/git-workflow/pull/10 +status: done --- # TASK-docs-align-workflow-instructions: Align workflow instructions @@ -64,12 +64,12 @@ status: in_progress 2. [x] Точечно согласовать ветки, подготовку коммитов, проверки и релиз через PR. 3. [x] Проверить ссылки, выполнить `composer validate --strict` и проверку установки документации во временный каталог. 4. [x] Провести самопроверку и независимое ревью, устранить замечания. -5. [ ] Создать PR с меткой `pi`, заполнить ссылку, дождаться CI и подготовить задачу к приёмке. +5. [x] Создать PR с меткой `pi`, заполнить ссылку, дождаться CI и подготовить задачу к приёмке. ## 5. Критерии приёмки (Definition of Done) - [x] Все обязательные требования выполнены; инструкции не требуют прямой записи в целевые ветки. - [x] Проверки Composer и документации успешны; независимое ревью не содержит блокирующих замечаний. -- [ ] PR открыт, задача связана с ним и готова к приёмке; версии и теги не выпускались. +- [x] PR открыт, задача связана с ним и готова к приёмке; версии и теги не выпускались. ## 6. Самопроверка (Verification) ```bash @@ -91,17 +91,18 @@ git diff --check - Самопроверка полного diff выполнена; уточнены синхронизация через выбранную базу и `--ff-only`, а также порядок patch-релиза для закрытой production line. - Независимое ревью технического писателя: одобрено, блокирующих замечаний нет; повторно проверены параметры генератора, 46 локальных ссылок и якорей, `composer validate --strict` и `git diff --check`. - Перед публикацией сохранено явное правило `done` до окончательного одобрения PR реализации; отдельный PR постановки не завершает будущую реализацию. -- Публикация PR и удалённый CI — следующий шаг. Фактические merge, релизы и теги не выполнялись; vendor, код и зависимости не изменялись. +- Открыт PR [#10](https://github.com/prikotov/git-workflow/pull/10) с меткой `pi`; CI `validate` успешен. Задача финализируется в той же ветке до окончательного одобрения; после служебного коммита проверки повторяются. +- Фактические merge, релизы и теги не выполнялись; vendor, код и зависимости не изменялись. ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. ## 8. Источники (Sources) -- [Ветки](../docs/git-workflow/branches.md). -- [Коммиты](../docs/git-workflow/commits.md). -- [Запросы на слияние](../docs/git-workflow/pull-request.md). -- [Релизы](../docs/git-workflow/release.md). +- [Ветки](../../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) @@ -111,3 +112,4 @@ git diff --check | Дата | Автор (роль) | Изменение | | :--- | :--- | :--- | | 2026-09-11 03:45:03 (1789098303) | Технический писатель (pi) | Создание задачи по согласованному плану | +| 2026-09-11 | Лид (pi) | Реализация и независимое ревью завершены; PR #10 опубликован, CI успешен, задача подготовлена к приёмке | From a496b55b3d908cdceb90d23b59267599678ad8b6 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Fri, 11 Sep 2026 22:07:45 +0700 Subject: [PATCH 03/40] =?UTF-8?q?docs(workflow):=20clarify=20release=20ste?= =?UTF-8?q?ps=20/=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8=D1=82=D1=8C=20?= =?UTF-8?q?=D1=88=D0=B0=D0=B3=D0=B8=20=D1=80=D0=B5=D0=BB=D0=B8=D0=B7=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 8 +-- docs/git-workflow/deploy.md | 4 +- docs/git-workflow/pull-request.md | 8 +-- docs/git-workflow/release-checklists.md | 26 ++++---- docs/git-workflow/release.md | 66 ++++++++++--------- docs/git-workflow/releases/index.md | 11 ++-- .../templates/release-plan.template.md | 30 +++++---- ...K-docs-align-workflow-instructions.todo.md | 16 ++++- 8 files changed, 92 insertions(+), 77 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index d5af766..c9404a3 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -92,10 +92,10 @@ git switch -c hotfix/x.y.z- vX.Y.Z ## Синхронизация -- `task/*` синхронизируется со своей базой: `master` для обычной разработки, активной `release/x.y` для стабилизации и подготовки релиза. -- База синхронизации совпадает с целью PR; не подтягивай `master` в рабочую ветку релиза. -- Локальная `release/*` обновляется только из одноимённой ветки `origin` через `--ff-only`; изменения в неё поступают через PR, новые feature commits из `master` не подтягиваются. -- `hotfix/*` после merge должен присутствовать в active `release/x.y` и в `master`. +- Рабочая ветка `task/` синхронизируется с веткой, от которой создана: `master` для обычной разработки или активной релизной веткой `release/x.y` для стабилизации и подготовки релиза. +- Ветка для синхронизации совпадает с целевой веткой PR; не подтягивай изменения из ветки `master` в рабочую ветку подготовки релиза. +- Локальная релизная ветка `release/x.y` обновляется только из одноимённой ветки удалённого репозитория `origin` через `--ff-only`; изменения в неё поступают через PR, новые функции из ветки `master` не подтягиваются. +- Изменения из рабочей ветки `hotfix/x.y.z-` должны попасть в выбранную ветку патч-релиза и в ветку `master`; целевая ветка определяется по [правилам срочного исправления](release.md#hotfix-и-patch-release). - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. В рабочей ветке выбери базу и получи её актуальное состояние: diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index b5102c8..2449873 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,8 +28,8 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Подготовить и стабилизировать active `release/x.y`; релизные файлы включить через одобренный PR из `task/*`. -2. Проверить слитый коммит `release/x.y`, создать на нём неизменяемый tag `vX.Y.Z` и опубликовать только этот тег по [процессу релиза](release.md#выпуск-релиза). +1. Подготовить и стабилизировать релизную ветку `release/x.y`; релизные файлы включить через одобренный PR из рабочей ветки `task/`, созданной от этой релизной ветки. +2. Выполнить предрелизные проверки, включая обязательный запуск `make tests-e2e`, выбрать коммит релиза после слияния и опубликовать его неизменяемый тег `vX.Y.Z` по [процессу релиза](release.md#выпуск-релиза). 3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. 4. Провести post-check: основные user-flow, логи, метрики. 5. При проблеме остановить rollout и выпустить hotfix или patch release. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index bd85487..85947e0 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -38,10 +38,10 @@ package: prikotov/git-workflow ## Выбор base branch -- `task/*` для обычной разработки → `master`. -- `task/*` для стабилизации и подготовки релизных файлов создаётся от активной `release/x.y` → PR в эту же `release/x.y`. -- `hotfix/*` → активная `release/x.y`, если release line ещё жива; дополнительно обязателен merge-back в `master`. -- Если production line уже закрыта, восстанови `release/x.y` от production tag по [правилам релиза](release.md#hotfix-и-patch-release) и направь hotfix PR в неё; merge-back в `master` — отдельным PR сразу после patch release. +- Рабочая ветка `task/` для обычной разработки создаётся от ветки `master`; PR направляется в `master`. +- Рабочая ветка `task/` для стабилизации и подготовки релизных файлов создаётся от активной релизной ветки `release/x.y`; PR направляется в эту же релизную ветку. +- Рабочая ветка срочного исправления `hotfix/x.y.z-` направляется через PR в релизную ветку текущей рабочей версии, если та ещё активна. Дополнительно обязателен возврат изменений (merge-back) в ветку `master`. +- Если релизная ветка текущей рабочей версии уже закрыта, целевую ветку патч-релиза согласуй с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска патч-релиза. ## Обязательные проверки diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index f59f26d..f928dbc 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -12,29 +12,29 @@ package: prikotov/git-workflow - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. -- Для новой minor/major линии `release/x.y` создана от согласованного коммита `master`; patch использует текущую production line (при необходимости восстановленную от production tag). Активная линия только одна. -- Рабочие `task/*` для стабилизации и релизных файлов созданы от `release/x.y`, синхронизируются с ней и целятся PR в неё. +- Для новой основной или дополнительной версии (major/minor) релизная ветка `release/x.y` создана от согласованного коммита ветки `master`. Ветка для патч-релиза выбрана по [правилам срочного исправления](release.md#hotfix-и-patch-release); изменения следующей версии в него не включены. +- Рабочие ветки `task/` для стабилизации и подготовки релизных файлов созданы от активной релизной ветки `release/x.y`, синхронизируются с ней и направляются в неё через PR. - `CHANGELOG.md`, файлы версий и заполненный `docs/releases/vX.Y.Z/release-plan.md` подготовлены в рабочей ветке без автоматического коммита и тега. - Все правки, включая служебные обновления задачи, включены до окончательных проверок и одобрения PR. -- Для релиза выполнены `make check` и `make tests-e2e`; исключения допустимы только по [явной политике потребителя](pull-request.md#обязательные-проверки). -- Окончательное состояние PR одобрено пользователем, CI зелёный, merge в `release/x.y` подтверждён и выполнен через GitHub. -- Полный SHA результата слияния зафиксирован; состав, релизные файлы, обязательные проверки и CI проверены на этом SHA. -- После разрешения на выпуск неизменяемый тег создан только на проверенном слитом SHA; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). +- Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. +- Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в релизную ветку `release/x.y` подтверждено и выполнено через GitHub. +- Зафиксирован полный идентификатор (SHA) коммита релиза после слияния; состав и релизные файлы соответствуют согласованным. После проверок не появились непроверенные изменения кода, зависимостей или конфигурации. +- После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления - Определён текущий тег релиза на production `vX.Y.Z`. -- `hotfix/x.y.z-` создан от тега production, а не от `master`. +- Рабочая ветка срочного исправления `hotfix/x.y.z-` создана от тега рабочей среды, а не от ветки `master`. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Зафиксирован план возврата изменений в активную `release/x.y` и `master`. -- Hotfix проходит PR в `release/x.y`; если production line закрыта, она восстановлена от production tag по [правилам релиза](release.md#hotfix-и-patch-release). -- Проверки для срочного исправления пройдены до выпуска патч-релиза. -- Релизные файлы проходят отдельный PR из `task/*` от `release/x.y`; тег создаётся только после проверки результата слияния, как в чеклисте подготовки релиза. +- Зафиксирован план включения исправления в выбранную ветку патч-релиза и возврата изменений в ветку `master`. +- Исправление проходит PR в релизную ветку текущей рабочей версии. Если она закрыта, целевая ветка патч-релиза согласована с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). +- Проверки для срочного исправления, включая предрелизный запуск `make tests-e2e`, пройдены до выпуска патч-релиза. +- Релизные файлы проходят отдельный PR из рабочей ветки `task/`, созданной от выбранной релизной ветки; тег создаётся на коммите после слияния, как в чеклисте подготовки релиза. ## Чеклист выкладки -- Выбран опубликованный неизменяемый тег релиза `vX.Y.Z` на проверенном слитом коммите `release/x.y`. -- Заполненный `docs/releases/vX.Y.Z/release-plan.md` уже включён в этот тег через PR. +- Выбран опубликованный неизменяемый тег релиза `vX.Y.Z`, указывающий на согласованный коммит релизной ветки `release/x.y` после слияния. +- Файл плана `docs/releases/vX.Y.Z/release-plan.md` включён через PR и присутствует в версии, отмеченной этим тегом. - Web и Workers будут выкачены на один и тот же тег. - В `release-plan.md` зафиксированы миграции, порядок их применения и риск окна несовместимости. - В `release-plan.md` зафиксирован план исправления без отката. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 151a733..fdc9277 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,16 +4,16 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Этот гайд фиксирует модель релизов (release model) проекта-потребителя: `master` как integration branch, одна active `release/x.y`, production deploy по immutable `tag` `vX.Y.Z`. +Этот гайд описывает модель релизов проекта-потребителя: интеграционную ветку `master`, одну активную релизную ветку `release/x.y` и выкладку в рабочую среду (production) по неизменяемому тегу `vX.Y.Z`. -## Release model +## Модель релизов -- `master` содержит текущую интеграцию задач и может опережать production. -- Перед production выпуском из выбранного commit в `master` создаётся `release/x.y`. -- В `release/x.y` допускаются только stabilizing changes: bugfix, release docs, безопасные мелкие правки — через PR из рабочих веток. -- Прямые коммиты в `master` и `release/*` запрещены; релизные файлы готовятся в `task/*` от активной `release/x.y`. -- Production всегда разворачивается по **конкретному tag**, а не по branch head. -- Одновременно поддерживается только одна active `release/x.y`. +- Ветка `master` объединяет изменения задач и может опережать версию в рабочей среде. +- Перед выпуском из выбранного коммита ветки `master` создаётся релизная ветка `release/x.y`. +- В релизную ветку допускаются только изменения для стабилизации: исправления ошибок, релизные документы и безопасные мелкие правки — через запросы на слияние (Pull Request, PR) из рабочих веток. +- Прямые коммиты в целевые ветки `master` и `release/*` запрещены. Релизные файлы готовятся в рабочей ветке `task/`, созданной от активной релизной ветки `release/x.y`. +- Рабочая среда всегда разворачивается по **конкретному тегу**, а не по последнему коммиту ветки. +- Одновременно поддерживается только одна активная релизная ветка `release/x.y`. ## SemVer и линии релиза @@ -39,7 +39,7 @@ package: prikotov/git-workflow ## Подготовка коммитов -Сообщения готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. Это относится и к релизным коммитам; обязательного помощника нет. +Сообщения готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. Это относится и к релизным коммитам: генератор сообщений не используется. ```bash git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" @@ -65,17 +65,17 @@ 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 и возврат изменений в ветку `master` определяются по [правилам срочного исправления](#hotfix-и-patch-release). ## План релиза -Для каждого production release в рабочей ветке подготовки, до одобрения PR и создания тега, создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. +Для каждого релиза в рабочей ветке подготовки, до одобрения PR и создания тега, создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. - место хранения: `docs/releases/`; - шаблон: [release-plan.template.md](./templates/release-plan.template.md). - без заполненного `release-plan.md` deploy не начинается. -В `task/*` от активной `release/x.y`, после выбора версии (тег ещё не создан): +В рабочей ветке `task/`, созданной от активной релизной ветки `release/x.y`, после выбора версии (тег ещё не создан): ```bash mkdir -p docs/releases/vX.Y.Z @@ -89,6 +89,8 @@ cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/rel - проверки после deploy; - план действий при проблеме после релиза через hotfix или patch release. +План описывает предстоящие действия, а не подтверждает их выполнение. Фактические результаты проверок и выкладки фиксируйте в комментариях к PR подготовки релиза; не дописывайте их в одобренную ветку и не перемещайте тег ради обновления отчёта. + ## Работа с CHANGELOG Генерируйте файлы только в рабочей ветке подготовки релиза. Если проект использует `marcocesarato/php-conventional-changelog`, документированный вызов без автоматического коммита и тега: @@ -116,7 +118,7 @@ git diff ### 1. Подготовка файлов через PR -После стабилизации создайте рабочую ветку от активной линии: +После стабилизации создайте рабочую ветку подготовки релиза от активной релизной ветки `release/x.y`. Замените `x.y` и `x-y-z` выбранными номерами версии: ```bash git switch release/x.y @@ -126,19 +128,19 @@ git switch -c task/prepare-release-x-y-z 1. Выберите версию по SemVer, подготовьте `CHANGELOG.md`, файлы версий и `docs/releases/vX.Y.Z/release-plan.md` в этой ветке. 2. Проверьте diff и создайте коммит вручную по [commits.md](commits.md). -3. Откройте PR из `task/*` в `release/x.y` по [правилам PR](pull-request.md). Не синхронизируйте эту рабочую ветку с `master`. -4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Для релиза обязательны `make check` и `make tests-e2e`; исключения или замены допустимы только по [явной политике потребителя](pull-request.md#обязательные-проверки). -5. Дождитесь зелёного CI, одобрения окончательного состояния PR и подтверждения merge пользователем; выполните merge через GitHub. После одобрения никаких новых коммитов без повторных проверок и нового одобрения. +3. Откройте PR из рабочей ветки подготовки в релизную ветку `release/x.y` по [правилам PR](pull-request.md). Не синхронизируйте эту рабочую ветку с веткой `master`. +4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Перед релизом выполните `make check` и обязательно запустите сквозные тесты командой `make tests-e2e`; дождитесь успешного завершения. Проектные исключения для `make check` не отменяют предрелизный запуск сквозных тестов. +5. Дождитесь успешных автоматических проверок PR (CI), одобрения окончательного состояния PR и подтверждения слияния пользователем; выполните слияние через GitHub. Если после одобрения нужны изменения, следуйте [порядку повторного одобрения](pull-request.md#подготовка-pr). -### 2. Проверка слитого коммита и создание тега +### 2. Выбор коммита и создание тега -- Зафиксируйте полный SHA коммита, полученного после merge PR в `release/x.y` (при squash это новый SHA), а не SHA рабочей ветки. -- Получите актуальную целевую ветку и убедитесь, что выбранный SHA принадлежит ей. Проверьте состав релиза и все релизные файлы на этом SHA. -- Проведите обязательные релизные проверки и дождитесь зелёного CI **именно для этого слитого SHA**. Проверки PR до merge не заменяют проверку результата слияния. -- Если нужны исправления — новый `task/*` от `release/x.y`, новый PR, проверки и одобрение; тег пока не создавайте. -- Если линия сдвинулась, не подменяйте проверенный SHA текущим head: заново согласуйте состав и проверьте выбранный коммит. +- Зафиксируйте полный идентификатор (SHA) коммита, полученного после слияния PR в релизную ветку `release/x.y`, а не идентификатор коммита рабочей ветки. +- Получите актуальное состояние целевой ветки и убедитесь, что выбранный коммит принадлежит ей и содержит согласованные релизные файлы. +- Убедитесь, что после обязательных проверок не появились непроверенные изменения кода, зависимостей или конфигурации. Если появились — проверьте их по правилам проекта. Новый идентификатор коммита после слияния сам по себе не требует повторного запуска всех проверок или отдельного CI после слияния; обязательный предрелизный запуск `make tests-e2e` сохраняется. +- Если нужны исправления — подготовьте их в новой рабочей ветке `task/` от релизной ветки `release/x.y`, затем проведите PR, проверки и одобрение; тег пока не создавайте. +- Если в релизную ветку поступили другие изменения, не заменяйте выбранный коммит её последним коммитом автоматически: заново согласуйте состав релиза. -Только после этих проверок и разрешения на выпуск создайте тег на зафиксированном SHA. В примере замените `VERIFIED_MERGED_SHA` полным проверенным SHA, а `X.Y.Z` — выбранной версией: +После выполнения этих условий и разрешения на выпуск создайте тег на выбранном коммите. В примере замените `VERIFIED_MERGED_SHA` полным идентификатором коммита, а `X.Y.Z` — выбранной версией: ```bash release_commit=VERIFIED_MERGED_SHA @@ -152,7 +154,7 @@ git push --no-follow-tags origin refs/tags/vX.Y.Z:refs/tags/vX.Y.Z ### 3. GitHub Release -Убедитесь, что опубликованный тег указывает на проверенный SHA. Создайте GitHub Release только для уже существующего удалённого тега: +Убедитесь, что опубликованный тег указывает на выбранный коммит релиза. Создайте GitHub Release только для уже существующего удалённого тега: ```bash gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md @@ -164,15 +166,15 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md Срочный hotfix не делается от `master`. -Базовый flow: -1. определить текущий production tag `vX.Y.Z`; -2. создать `hotfix/x.y.z-` от этого tag; -3. исправить проблему и провести обязательные проверки; -4. влить hotfix через одобренный PR в active `release/x.y`; -5. подготовить patch release `vX.Y.(Z+1)` в `task/*` от этой линии и выпустить по описанному выше процессу PR → проверка слитого SHA → конкретный тег; -6. выполнить merge-back hotfix changes в `master` отдельным PR из рабочей ветки. +Если активная релизная ветка соответствует версии в рабочей среде: +1. Определите текущий тег рабочей среды `vX.Y.Z`. +2. Создайте рабочую ветку срочного исправления `hotfix/x.y.z-` от этого тега. +3. Исправьте проблему и проведите обязательные проверки. +4. Включите исправление через одобренный PR в релизную ветку `release/x.y`. +5. Подготовьте патч-релиз `vX.Y.(Z+1)` в рабочей ветке `task/`, созданной от этой релизной ветки. Используйте описанный выше порядок: PR подготовки → обязательные проверки, включая `make tests-e2e` → слияние → создание конкретного тега. +6. Верните изменения срочного исправления в ветку `master` отдельным PR из рабочей ветки. -Если production line уже закрыта, восстановите `release/x.y` от текущего production tag и направьте hotfix PR в неё. При наличии другой активной линии сначала согласуйте её закрытие: две активные линии запрещены. Далее действует тот же порядок подготовки файлов через PR и тега после проверки слитого коммита; merge-back в `master` — отдельным PR сразу после patch release. +Если релизная ветка текущей рабочей версии уже закрыта, срочное исправление всё равно начинается от её тега. До открытия PR согласуйте целевую ветку патч-релиза с пользователем; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска. Эта инструкция не предписывает закрывать другую активную релизную ветку или включать в патч-релиз изменения следующей версии. ## Recovery Policy diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index aeaf5ad..cc5862e 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -4,7 +4,7 @@ package: prikotov/git-workflow # Артефакты релиза -Этот раздел описывает документы, которые создаются для конкретного production релиза. +Этот раздел описывает документы, которые создаются для конкретного релиза в рабочую среду (production). ## Структура @@ -13,11 +13,12 @@ package: prikotov/git-workflow ## Правила -- Для каждого production релиза каталог `docs/releases/vX.Y.Z/` и его файлы готовятся в `task/*` от активной `release/x.y` до окончательного одобрения PR. -- Артефакты включаются в `release/x.y` через PR до создания тега на проверенном слитом коммите: [процесс релиза](../release.md#выпуск-релиза). +- Для каждого релиза каталог `docs/releases/vX.Y.Z/` и его файлы создаются в рабочей Git-ветке `task/`, созданной от активной релизной ветки `release/x.y`. Например, `task/prepare-release-0-9-3` — имя ветки, а не путь каталога. +- Подготовленные документы включаются в релизную ветку через одобренный запрос на слияние (Pull Request, PR), до создания тега: [процесс релиза](../release.md#выпуск-релиза). - Минимально обязательный файл в каталоге релиза: `release-plan.md`. -- `release-plan.md` фиксирует состав релиза, риски, миграции, порядок deploy, post-check и план действий через hotfix или patch release. -- Для `hotfix` и `patch release` создаётся отдельный каталог по новому тегу релиза. +- Файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. +- План описывает предстоящие действия. Фактические результаты проверок и выкладки записываются в комментариях к PR подготовки релиза, а не заранее в плане. +- Для срочного исправления (hotfix) и патч-релиза (patch release) создаётся отдельный каталог с номером новой версии. ## Шаблон diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 7d1e72a..2d6e6e5 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,13 +1,15 @@ # План релиза vX.Y.Z +Этот документ заполняется до одобрения PR (запроса на слияние) подготовки релиза и создания тега. Здесь описываются будущие действия и критерии их успешности. Фактические результаты проверок и выкладки фиксируются в комментариях к этому PR, без изменения одобренной ветки или тега. + ## Метаданные - Тег релиза: `vX.Y.Z` - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: - Линия релиза: `release/x.y` -- Рабочая ветка подготовки: `task/…` от `release/x.y` -- PR подготовки релиза в `release/x.y`: +- Рабочая ветка подготовки: `task/`, созданная от релизной ветки `release/x.y` +- PR подготовки релиза в релизную ветку `release/x.y`: - Ответственный: - Плановая дата deploy: @@ -30,21 +32,21 @@ 1. Web 2. Workers -## Проверки перед deploy +## План проверок перед выкладкой -- Этот план и остальные релизные файлы включены через PR до создания тега -- Окончательное состояние PR одобрено; обязательные проверки и CI слитого коммита `release/x.y` успешны -- Тег релиза создан на этом проверенном коммите; в `origin` опубликован только конкретный тег -- Подготовлены обязательные изменения в env -- В документе зафиксированы миграции, порядок их применения и риск окна несовместимости -- Подготовлены команды health-check +- Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов +- Убедиться, что этот план и остальные релизные файлы включены через одобренный PR до создания тега +- Убедиться, что тег указывает на выбранный коммит релиза после слияния и опубликован в `origin` +- Проверить необходимые изменения переменных окружения: +- Проверить готовность миграций, порядок их применения и риск окна несовместимости: +- Команды проверки работоспособности (health-check) и ожидаемые результаты: -## Проверки после deploy +## План проверок после выкладки -- Основные пользовательские сценарии: -- Логи: -- Очереди и воркеры: -- Build version и git SHA: +- Основные пользовательские сценарии и ожидаемые результаты: +- Проверяемые логи и признаки ошибок: +- Ожидаемое состояние очередей и обработчиков: +- Способ проверки версии сборки и идентификатора коммита (SHA): ## Действия при проблеме после релиза diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 55c156b..d84bd82 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 04:02:03 (1789099323) +completed: 2026-09-11 15:05:35 (1789139135) cancelled: value: V2 complexity: C2 @@ -81,7 +81,7 @@ git diff --check ### Результат выполнения - Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. -- Релизные файлы готовятся в `task/*` от `release/x.y`, проходят PR и окончательное одобрение; конкретный неизменяемый тег создаётся только на проверенном слитом SHA. Автокоммит, автотег и публикация всех тегов исключены. +- Релизные файлы готовятся в рабочей ветке `task/`, созданной от релизной ветки `release/x.y`, и проходят PR с окончательным одобрением. Конкретный неизменяемый тег создаётся на согласованном коммите релиза после слияния. Автокоммит, автотег и публикация всех тегов исключены. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Параметры `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`. @@ -89,11 +89,20 @@ git diff --check - `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. -- Независимое ревью технического писателя: одобрено, блокирующих замечаний нет; повторно проверены параметры генератора, 46 локальных ссылок и якорей, `composer validate --strict` и `git diff --check`. +- Первоначальное независимое ревью технического писателя одобрило изменения, но не выявило перечисленных ниже смысловых недостатков. Его заключение не используется как подтверждение исправленной редакции; повторная вычитка и исправления выполнены лично, без делегирования, по запросу пользователя. - Перед публикацией сохранено явное правило `done` до окончательного одобрения PR реализации; отдельный PR постановки не завершает будущую реализацию. - Открыт PR [#10](https://github.com/prikotov/git-workflow/pull/10) с меткой `pi`; CI `validate` успешен. Задача финализируется в той же ветке до окончательного одобрения; после служебного коммита проверки повторяются. - Фактические merge, релизы и теги не выполнялись; vendor, код и зависимости не изменялись. +### Доработка после замечаний пользователя + +- Задача возвращена в `review` перед исправлениями. Во взаимосвязанных документах явно различены имена рабочих веток, пути файлов и идентификаторы коммитов. +- Сохранён обязательный предрелизный запуск `make tests-e2e`. Убрано добавленное требование полного повторного прогона и отдельного CI только из-за нового идентификатора коммита после слияния. Непроверенные изменения проверяются по правилам проекта. +- Убрано предписание закрывать другую активную релизную ветку ради срочного исправления. Для закрытой ветки текущей рабочей версии не подставляется ветка следующего релиза; выбор целевой ветки согласуется с пользователем. +- План релиза теперь содержит будущие действия и ожидаемые результаты, а не утверждения о ещё не выполненных проверках и выкладке. Фактические результаты записываются в комментариях к PR подготовки релиза. +- Повторно выполнены `composer validate --strict`, `git diff --check`, установка в `/tmp/git-workflow-revision-init.uTaXxW` и повторная установка: 11 документов скопированы, затем 11 пропущены; копия полностью совпадает с исходниками. +- После завершения правок задача снова оформляется в `done` до запроса окончательного одобрения. Текущее состояние автоматических проверок доступно в PR #10; предыдущие результаты CI относятся к предыдущей редакции. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. @@ -113,3 +122,4 @@ git diff --check | :--- | :--- | :--- | | 2026-09-11 03:45:03 (1789098303) | Технический писатель (pi) | Создание задачи по согласованному плану | | 2026-09-11 | Лид (pi) | Реализация и независимое ревью завершены; PR #10 опубликован, CI успешен, задача подготовлена к приёмке | +| 2026-09-11 | Технический писатель (pi) | Повторная личная вычитка по замечаниям пользователя: исправлены терминология, проверки релиза, сценарий срочного исправления и шаблон плана; проверки повторены | From e542dc0c244bdb4e59ce12f5c6f67df4cd76f2a0 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Fri, 11 Sep 2026 22:37:20 +0700 Subject: [PATCH 04/40] =?UTF-8?q?docs(release):=20release=20from=20main=20?= =?UTF-8?q?branch=20/=20=D0=B2=D1=8B=D0=BF=D1=83=D1=81=D0=BA=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20=D0=B8=D0=B7=20=D0=BE=D1=81=D0=BD=D0=BE=D0=B2=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=20=D0=B2=D0=B5=D1=82=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 41 ++++----- docs/git-workflow/deploy.md | 4 +- docs/git-workflow/pull-request.md | 11 +-- docs/git-workflow/release-checklists.md | 18 ++-- docs/git-workflow/release.md | 83 +++++++++++-------- docs/git-workflow/releases/index.md | 5 +- .../templates/release-plan.template.md | 13 ++- ...K-docs-align-workflow-instructions.todo.md | 18 +++- 8 files changed, 106 insertions(+), 87 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index c9404a3..dbc8a75 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -15,9 +15,9 @@ package: prikotov/git-workflow ## Целевая модель -- `master` — integration branch для обычной разработки. +- `master` или `main` — основная ветка разработки и источник обычных релизов. В примерах ниже используется `master`; для проекта с `main` замените имя в командах. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. -- `release/x.y` — активная линия стабилизации релиза. +- `release/x.y` — ветка, фиксирующая выбранный коммит основной ветки для обычного релиза; самостоятельная разработка в ней не ведётся. Исключение — отдельный сценарий срочного исправления рабочей версии. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки. - Одновременно поддерживается только одна активная `release/x.y`. @@ -47,7 +47,7 @@ package: prikotov/git-workflow ### Task branch -Для обычной разработки и документации база и цель PR — `master`. +Для обычной разработки, исправлений перед релизом, документации и подготовки релизных файлов база и цель PR — основная ветка `master` (либо `main`). ```bash git switch master @@ -55,29 +55,18 @@ git pull --ff-only origin master git switch -c task/ ``` -Для стабилизации и подготовки релизных файлов база и цель PR — активная `release/x.y`: - -```bash -git switch release/x.y -git pull --ff-only origin release/x.y -git switch -c task/ -``` +Только для подготовки файлов **срочного исправления от рабочего тега** рабочая ветка может создаваться от выбранной ветки патч-релиза; PR направляется в неё по [отдельному сценарию](release.md#hotfix-и-patch-release). Это не источник обычного релиза, даже если его версия повышается только на `patch`. ### Release branch -Создаётся только после решения, что конкретный набор изменений идёт в production. - -```bash -git switch master -git pull --ff-only origin master -git switch -c release/x.y -git push -u origin release/x.y -``` +Для обычного релиза создаётся от согласованного актуального коммита основной ветки **после включения в неё кода и релизных файлов через PR**. Точная последовательность и команды — в [процессе релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки). Правила для `release/x.y`: -- в неё попадают только stabilizing changes; -- новые feature PR продолжают идти в `master`; -- после выпуска patch changes из release line не должны теряться в `master`. +- предыдущая релизная ветка не используется как база нового обычного релиза; +- тег обычного релиза отмечает выбранный коммит, уже присутствующий в истории основной ветки; +- найденные ошибки сначала исправляются через PR в основную ветку, затем состав релиза выбирается заново из неё; +- новые задачи продолжают включаться в основную ветку и не меняют зафиксированный состав автоматически; +- занятое имя ветки не разрешает принудительную перезапись: сначала завершается предыдущая линия по правилам ниже. ### Hotfix branch @@ -92,16 +81,16 @@ git switch -c hotfix/x.y.z- vX.Y.Z ## Синхронизация -- Рабочая ветка `task/` синхронизируется с веткой, от которой создана: `master` для обычной разработки или активной релизной веткой `release/x.y` для стабилизации и подготовки релиза. -- Ветка для синхронизации совпадает с целевой веткой PR; не подтягивай изменения из ветки `master` в рабочую ветку подготовки релиза. -- Локальная релизная ветка `release/x.y` обновляется только из одноимённой ветки удалённого репозитория `origin` через `--ff-only`; изменения в неё поступают через PR, новые функции из ветки `master` не подтягиваются. +- Рабочая ветка обычной задачи или подготовки обычного релиза синхронизируется с основной веткой `master`/`main`, в которую направляется PR. +- Рабочая ветка подготовки срочного патч-релиза синхронизируется с выбранной веткой этого исправления. Не подтягивай туда ещё не выпущенные изменения основной ветки. +- Локальная релизная ветка обновляется только из одноимённой ветки `origin` через `--ff-only`. Зафиксированный состав обычного релиза не обновляется из основной ветки автоматически. - Изменения из рабочей ветки `hotfix/x.y.z-` должны попасть в выбранную ветку патч-релиза и в ветку `master`; целевая ветка определяется по [правилам срочного исправления](release.md#hotfix-и-patch-release). - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. В рабочей ветке выбери базу и получи её актуальное состояние: ```bash -base=master # Для стабилизации и подготовки релиза: base=release/x.y +base=master # Для проекта с main: base=main. Для срочного патч-релиза — согласованная ветка исправления. git fetch origin ``` @@ -122,5 +111,5 @@ git rebase "origin/$base" ## Завершение - После merge PR рабочую ветку нужно удалить локально и в `origin`. -- После выпуска `release/x.y`, когда line закрыта и merge-back завершён, release branch можно удалить. +- Релизную ветку можно удалить после завершения работы с выбранным составом и закрытия линии. Для выпущенной версии сохраняется неизменяемый тег; для отменённого кандидата тег не создаётся. При срочном исправлении сначала завершается возврат изменений в основную ветку. Обычный релиз отдельного возврата не требует: его изменения уже включены туда до выпуска. - Hotfix branch удаляется сразу после merge-back в целевые ветки. diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 2449873..728747c 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,8 +28,8 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Подготовить и стабилизировать релизную ветку `release/x.y`; релизные файлы включить через одобренный PR из рабочей ветки `task/`, созданной от этой релизной ветки. -2. Выполнить предрелизные проверки, включая обязательный запуск `make tests-e2e`, выбрать коммит релиза после слияния и опубликовать его неизменяемый тег `vX.Y.Z` по [процессу релиза](release.md#выпуск-релиза). +1. Для обычного релиза включить код, исправления и релизные файлы через одобренные PR (запросы на слияние) в основную ветку `master`/`main`. Рабочая ветка подготовки создаётся от неё, не от предыдущей релизной ветки. +2. Зафиксировать согласованный актуальный коммит основной ветки, создать от него релизную ветку `release/x.y` и после обязательных проверок, включая `make tests-e2e`, опубликовать тег `vX.Y.Z` на том же коммите по [процессу релиза](release.md#выпуск-релиза). Срочное исправление от рабочего тега готовится по [отдельному сценарию](release.md#hotfix-и-patch-release). 3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. 4. Провести post-check: основные user-flow, логи, метрики. 5. При проблеме остановить rollout и выпустить hotfix или patch release. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 85947e0..363492d 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -38,8 +38,9 @@ package: prikotov/git-workflow ## Выбор base branch -- Рабочая ветка `task/` для обычной разработки создаётся от ветки `master`; PR направляется в `master`. -- Рабочая ветка `task/` для стабилизации и подготовки релизных файлов создаётся от активной релизной ветки `release/x.y`; PR направляется в эту же релизную ветку. +- Рабочая ветка `task/` для обычной разработки, исправлений перед релизом и подготовки релизных файлов создаётся от актуальной основной ветки `master` или `main`; PR направляется туда же. Далее `master` означает основную ветку проекта. +- Ветка `release/x.y` обычного релиза создаётся только после включения кода и релизных файлов в основную ветку. PR подготовки обычного релиза не направляется в предыдущую релизную ветку. +- Подготовка файлов срочного исправления от рабочего тега — исключение: рабочая ветка создаётся от выбранной ветки патч-релиза, PR направляется в неё по [отдельному сценарию](release.md#hotfix-и-patch-release). - Рабочая ветка срочного исправления `hotfix/x.y.z-` направляется через PR в релизную ветку текущей рабочей версии, если та ещё активна. Дополнительно обязателен возврат изменений (merge-back) в ветку `master`. - Если релизная ветка текущей рабочей версии уже закрыта, целевую ветку патч-релиза согласуй с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска патч-релиза. @@ -57,7 +58,7 @@ package: prikotov/git-workflow - Сделай self-review: [Ревью кода (Code Review)](code-review.md). - Используй CLI-инструменты: `git`, `gh`. - Сделай push: `git push -u origin HEAD`. -- Создай PR с явной базой: `gh pr create --base --head "$(git branch --show-current)"`; `` — `master` или выбранная `release/x.y`. +- Создай PR с явной базой: `gh pr create --base --head "$(git branch --show-current)"`; `` — основная ветка `master`/`main` для обычной разработки и релиза либо согласованная ветка срочного исправления. - Тело PR передавай через `gh pr create --body-file`. - Предпочитай `--body-file -` (stdin) или файл в `tmp/`. - Связь задачи с PR и переходы статусов веди по установленным в проекте правилам `todo-md`. Формат полей и механика задач не определяются этим пакетом. @@ -112,12 +113,12 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- Возврат изменений (merge-back) из `release/x.y` в `master`, в том числе hotfix, выполняй отдельным PR из рабочей ветки. +- Возврат срочного исправления (merge-back) в основную ветку выполняй отдельным PR из рабочей ветки. Обычный релиз не должен ждать такого возврата после выпуска: его код и релизные файлы включаются в основную ветку заранее. ## После merge - После merge PR в `master` переключись на `master` и обнови его: `git pull --ff-only origin master`. -- После merge PR в `release/x.y` переключись на эту release line только если продолжается стабилизация; иначе вернись в `master`. +- После слияния PR срочного исправления в релизную ветку оставайся на этой линии только при продолжении работы над исправлением; иначе вернись в основную ветку. - Удали рабочую ветку локально и в `origin`. - Проверь, что рабочее дерево чистое: `git status`. - Предложи пользователю следующую задачу. diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index f928dbc..275921d 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -8,17 +8,19 @@ package: prikotov/git-workflow ## Чеклист подготовки релиза -- Состав релиза согласован, лишние изменения остаются в `master`. +Этот чеклист относится к обычному релизу, включая обычное повышение `patch`. Срочное исправление от рабочего тега описано отдельно ниже. Основная ветка проекта — `master` или `main`. + +- Согласован состав актуальной основной ветки, а не выбран набор изменений из предыдущей релизной ветки. - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. -- Для новой основной или дополнительной версии (major/minor) релизная ветка `release/x.y` создана от согласованного коммита ветки `master`. Ветка для патч-релиза выбрана по [правилам срочного исправления](release.md#hotfix-и-patch-release); изменения следующей версии в него не включены. -- Рабочие ветки `task/` для стабилизации и подготовки релизных файлов созданы от активной релизной ветки `release/x.y`, синхронизируются с ней и направляются в неё через PR. +- Рабочие ветки `task/` для исправлений и подготовки релизных файлов созданы от актуальной основной ветки, синхронизируются с ней и направляются в неё через PR (запросы на слияние). - `CHANGELOG.md`, файлы версий и заполненный `docs/releases/vX.Y.Z/release-plan.md` подготовлены в рабочей ветке без автоматического коммита и тега. - Все правки, включая служебные обновления задачи, включены до окончательных проверок и одобрения PR. - Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. -- Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в релизную ветку `release/x.y` подтверждено и выполнено через GitHub. -- Зафиксирован полный идентификатор (SHA) коммита релиза после слияния; состав и релизные файлы соответствуют согласованным. После проверок не появились непроверенные изменения кода, зависимостей или конфигурации. +- Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в основную ветку подтверждено и выполнено через GitHub. +- После включения кода и релизных файлов зафиксирован полный идентификатор (SHA) согласованного актуального коммита основной ветки. Возможные изменения, вошедшие после PR подготовки, учтены; после проверок нет непроверенных изменений кода, зависимостей или конфигурации. +- Ветка `release/x.y` создана от этого коммита по [процессу релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки), не от предыдущей релизной ветки. Коммит тега обычного релиза принадлежит истории основной ветки; изменений только в релизной ветке нет. - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления @@ -28,12 +30,12 @@ package: prikotov/git-workflow - Объём срочного исправления минимален и не тянет несвязанные изменения. - Зафиксирован план включения исправления в выбранную ветку патч-релиза и возврата изменений в ветку `master`. - Исправление проходит PR в релизную ветку текущей рабочей версии. Если она закрыта, целевая ветка патч-релиза согласована с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). -- Проверки для срочного исправления, включая предрелизный запуск `make tests-e2e`, пройдены до выпуска патч-релиза. -- Релизные файлы проходят отдельный PR из рабочей ветки `task/`, созданной от выбранной релизной ветки; тег создаётся на коммите после слияния, как в чеклисте подготовки релиза. +- Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки успешны. +- Релизные файлы проходят отдельный PR из рабочей ветки `task/`, созданной от выбранной ветки исправления. Тег отмечает согласованный коммит после слияния в неё по [сценарию срочного исправления](release.md#hotfix-и-patch-release), а не текущий коммит основной ветки с ещё не выпущенными изменениями. ## Чеклист выкладки -- Выбран опубликованный неизменяемый тег релиза `vX.Y.Z`, указывающий на согласованный коммит релизной ветки `release/x.y` после слияния. +- Выбран опубликованный неизменяемый тег `vX.Y.Z`: для обычного релиза он указывает на согласованный коммит основной ветки, для срочного исправления — на коммит соответствующего патч-релиза. - Файл плана `docs/releases/vX.Y.Z/release-plan.md` включён через PR и присутствует в версии, отмеченной этим тегом. - Web и Workers будут выкачены на один и тот же тег. - В `release-plan.md` зафиксированы миграции, порядок их применения и риск окна несовместимости. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index fdc9277..352a966 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,16 +4,18 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Этот гайд описывает модель релизов проекта-потребителя: интеграционную ветку `master`, одну активную релизную ветку `release/x.y` и выкладку в рабочую среду (production) по неизменяемому тегу `vX.Y.Z`. +Обычный релиз выпускается из актуальной основной ветки проекта — `master` или `main`. Ниже в примерах используется `master`; если основная ветка называется `main`, замените имя в командах. Выкладка в рабочую среду (production) выполняется по неизменяемому тегу `vX.Y.Z`. ## Модель релизов -- Ветка `master` объединяет изменения задач и может опережать версию в рабочей среде. -- Перед выпуском из выбранного коммита ветки `master` создаётся релизная ветка `release/x.y`. -- В релизную ветку допускаются только изменения для стабилизации: исправления ошибок, релизные документы и безопасные мелкие правки — через запросы на слияние (Pull Request, PR) из рабочих веток. -- Прямые коммиты в целевые ветки `master` и `release/*` запрещены. Релизные файлы готовятся в рабочей ветке `task/`, созданной от активной релизной ветки `release/x.y`. +- Код, исправления и релизные файлы обычного релиза сначала включаются в основную ветку через запросы на слияние (Pull Request, PR). +- Рабочая ветка подготовки `task/` создаётся от актуальной основной ветки; PR направляется туда же, а не в предыдущую релизную ветку. +- После включения релизных файлов фиксируется актуальный коммит основной ветки. От него создаётся ветка `release/x.y`, и этот же коммит отмечается тегом после обязательных проверок. +- В обычном релизе не должно быть изменений, отсутствующих в основной ветке. Релизная ветка фиксирует выбранный состав, а не служит независимой веткой разработки. +- Прямые правки и коммиты в целевых ветках `master`, `main` и `release/*` запрещены. - Рабочая среда всегда разворачивается по **конкретному тегу**, а не по последнему коммиту ветки. - Одновременно поддерживается только одна активная релизная ветка `release/x.y`. +- Срочное исправление от рабочего тега — отдельное исключение: см. [Hotfix и patch release](#hotfix-и-patch-release). Оно не меняет источник обычных релизов. ## SemVer и линии релиза @@ -34,8 +36,8 @@ package: prikotov/git-workflow Тип релиза определяется по истории Conventional Commits: `fix` требует `patch`, `feat` — `minor`, а `BREAKING CHANGE` или `!` — `minor` при текущей версии `0.x` и `major` начиная с `1.0.0`. Выбранную версию явно передавайте генератору; его автоматическое повышение не заменяет эти правила, особенно для `0.x`. -- `patch` сохраняет текущую release line. -- `minor` и `major` открывают новую `release/x.y`. +- `patch` сохраняет номера `major.minor`, но не предписывает брать код из предыдущей релизной ветки. Обычный патч-релиз также выпускается из актуальной основной ветки. +- `minor` и `major` меняют номер релизной линии `x.y`. Выбор версии и выбор источника кода — разные решения. ## Подготовка коммитов @@ -53,19 +55,12 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## Release cut -Когда Product Owner и Team Lead зафиксировали состав релиза: +Фиксация состава релиза (release cut) выполняется **после включения кода и релизных файлов в основную ветку**, а не перед их подготовкой. Порядок выбора коммита и создания ветки приведён в разделе [«Выпуск релиза»](#выпуск-релиза). -```bash -git switch master -git pull --ff-only 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; -- если найден дефект рабочей среды, ветка срочного исправления создаётся от её текущего тега; целевая ветка PR и возврат изменений в ветку `master` определяются по [правилам срочного исправления](#hotfix-и-patch-release). +После фиксации: +- новые задачи продолжают включаться в основную ветку, но не попадают в уже выбранный состав автоматически; +- найденные ошибки исправляются через PR в основную ветку; затем заново согласуется коммит релиза из неё, а не добавляется код только в релизную ветку; +- исправление уже работающей версии от её тега выполняется отдельно по [правилам срочного исправления](#hotfix-и-patch-release). ## План релиза @@ -75,7 +70,7 @@ git push -u origin release/x.y - шаблон: [release-plan.template.md](./templates/release-plan.template.md). - без заполненного `release-plan.md` deploy не начинается. -В рабочей ветке `task/`, созданной от активной релизной ветки `release/x.y`, после выбора версии (тег ещё не создан): +Для обычного релиза — в рабочей ветке `task/`, созданной от актуальной основной ветки, после выбора версии (релизная ветка и тег ещё не созданы). Для срочного исправления источник указан в [отдельном сценарии](#hotfix-и-patch-release): ```bash mkdir -p docs/releases/vX.Y.Z @@ -118,41 +113,57 @@ git diff ### 1. Подготовка файлов через PR -После стабилизации создайте рабочую ветку подготовки релиза от активной релизной ветки `release/x.y`. Замените `x.y` и `x-y-z` выбранными номерами версии: +Для обычного релиза создайте рабочую ветку подготовки от актуальной основной ветки. Замените `x-y-z` выбранным номером версии: ```bash -git switch release/x.y -git pull --ff-only origin release/x.y +git switch master +git pull --ff-only origin master git switch -c task/prepare-release-x-y-z ``` 1. Выберите версию по SemVer, подготовьте `CHANGELOG.md`, файлы версий и `docs/releases/vX.Y.Z/release-plan.md` в этой ветке. 2. Проверьте diff и создайте коммит вручную по [commits.md](commits.md). -3. Откройте PR из рабочей ветки подготовки в релизную ветку `release/x.y` по [правилам PR](pull-request.md). Не синхронизируйте эту рабочую ветку с веткой `master`. +3. Откройте PR из рабочей ветки подготовки в основную ветку по [правилам PR](pull-request.md). Исправления и релизные файлы должны попасть туда до выпуска; рабочая ветка синхронизируется с этой же основной веткой. 4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Перед релизом выполните `make check` и обязательно запустите сквозные тесты командой `make tests-e2e`; дождитесь успешного завершения. Проектные исключения для `make check` не отменяют предрелизный запуск сквозных тестов. 5. Дождитесь успешных автоматических проверок PR (CI), одобрения окончательного состояния PR и подтверждения слияния пользователем; выполните слияние через GitHub. Если после одобрения нужны изменения, следуйте [порядку повторного одобрения](pull-request.md#подготовка-pr). -### 2. Выбор коммита и создание тега +### 2. Выбор коммита и создание релизной ветки -- Зафиксируйте полный идентификатор (SHA) коммита, полученного после слияния PR в релизную ветку `release/x.y`, а не идентификатор коммита рабочей ветки. -- Получите актуальное состояние целевой ветки и убедитесь, что выбранный коммит принадлежит ей и содержит согласованные релизные файлы. +- После слияния PR получите актуальное состояние основной ветки и согласуйте её текущий коммит как состав релиза. Если после PR подготовки туда вошли другие изменения, проверьте весь получившийся состав и соответствие релизных файлов, а не только исходный PR. +- Зафиксируйте полный идентификатор (SHA) выбранного коммита основной ветки. Нельзя выбирать коммит, существующий только в рабочей или предыдущей релизной ветке. - Убедитесь, что после обязательных проверок не появились непроверенные изменения кода, зависимостей или конфигурации. Если появились — проверьте их по правилам проекта. Новый идентификатор коммита после слияния сам по себе не требует повторного запуска всех проверок или отдельного CI после слияния; обязательный предрелизный запуск `make tests-e2e` сохраняется. -- Если нужны исправления — подготовьте их в новой рабочей ветке `task/` от релизной ветки `release/x.y`, затем проведите PR, проверки и одобрение; тег пока не создавайте. -- Если в релизную ветку поступили другие изменения, не заменяйте выбранный коммит её последним коммитом автоматически: заново согласуйте состав релиза. +- Если нужны исправления — проведите новый PR из рабочей ветки в основную ветку, затем заново согласуйте состав релиза из неё. Не добавляйте исправления только в релизную ветку. +- Более поздние изменения основной ветки не подменяют уже зафиксированный коммит автоматически. + +Перед созданием ветки убедитесь, что имя `release/x.y` свободно локально и в `origin`. Если оно занято, не берите прежнюю ветку за источник нового обычного релиза и не перезаписывайте её принудительно: сначала завершите предыдущую линию по [правилам веток](branches.md#завершение). После исправлений уже выбранного состава также сначала завершите работу с прежней релизной веткой; новый состав берётся из основной ветки. Это не разрешает менять опубликованные теги. + +Проверьте, что выбранный коммит входит в историю основной ветки, и создайте от него релизную ветку. Замените `VERIFIED_MAIN_SHA` полным согласованным идентификатором, а `x.y` — номером линии: + +```bash +release_commit=VERIFIED_MAIN_SHA +git fetch origin && + git merge-base --is-ancestor "$release_commit" origin/master && + git branch release/x.y "$release_commit" && + git push -u origin release/x.y +``` + +Если получение актуальных данных, проверка принадлежности основной ветке или создание ветки завершается ошибкой, выпуск останавливается. + +### 3. Создание и публикация тега -После выполнения этих условий и разрешения на выпуск создайте тег на выбранном коммите. В примере замените `VERIFIED_MERGED_SHA` полным идентификатором коммита, а `X.Y.Z` — выбранной версией: +После обязательных проверок и разрешения на выпуск создайте тег **на зафиксированном коммите**, а не на текущем конце релизной ветки. Для обычного релиза это выбранный коммит основной ветки из шага 2; для срочного исправления — коммит, определённый в [отдельном сценарии](#hotfix-и-patch-release). В примере замените `VERIFIED_RELEASE_SHA` полным идентификатором, а `X.Y.Z` — выбранной версией: ```bash -release_commit=VERIFIED_MERGED_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_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 ``` - Публикуется только конкретный тег, не все локальные теги; `git push --tags` запрещён. - Тег production неизменяем: не перемещайте, не перезаписывайте и не публикуйте его с `--force`. - На защищённой ветке не создаётся дополнительный релизный коммит; генератор после merge не запускается. -### 3. GitHub Release +### 4. GitHub Release Убедитесь, что опубликованный тег указывает на выбранный коммит релиза. Создайте GitHub Release только для уже существующего удалённого тега: @@ -171,7 +182,7 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md 2. Создайте рабочую ветку срочного исправления `hotfix/x.y.z-` от этого тега. 3. Исправьте проблему и проведите обязательные проверки. 4. Включите исправление через одобренный PR в релизную ветку `release/x.y`. -5. Подготовьте патч-релиз `vX.Y.(Z+1)` в рабочей ветке `task/`, созданной от этой релизной ветки. Используйте описанный выше порядок: PR подготовки → обязательные проверки, включая `make tests-e2e` → слияние → создание конкретного тега. +5. Подготовьте файлы срочного патч-релиза `vX.Y.(Z+1)` в рабочей ветке `task/`, созданной от этой релизной ветки. Включите их через одобренный PR в ту же ветку. После обязательных проверок, включая `make tests-e2e`, зафиксируйте коммит результата слияния и используйте [порядок публикации тега](#3-создание-и-публикация-тега). Этот экстренный сценарий не требует брать текущую основную ветку: в ней могут находиться ещё не выпущенные изменения. 6. Верните изменения срочного исправления в ветку `master` отдельным PR из рабочей ветки. Если релизная ветка текущей рабочей версии уже закрыта, срочное исправление всё равно начинается от её тега. До открытия PR согласуйте целевую ветку патч-релиза с пользователем; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска. Эта инструкция не предписывает закрывать другую активную релизную ветку или включать в патч-релиз изменения следующей версии. @@ -185,7 +196,7 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Рекомендации команды -- Перед 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 cc5862e..79df0ff 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -13,8 +13,9 @@ package: prikotov/git-workflow ## Правила -- Для каждого релиза каталог `docs/releases/vX.Y.Z/` и его файлы создаются в рабочей Git-ветке `task/`, созданной от активной релизной ветки `release/x.y`. Например, `task/prepare-release-0-9-3` — имя ветки, а не путь каталога. -- Подготовленные документы включаются в релизную ветку через одобренный запрос на слияние (Pull Request, PR), до создания тега: [процесс релиза](../release.md#выпуск-релиза). +- Для обычного релиза каталог `docs/releases/vX.Y.Z/` и его файлы создаются в рабочей Git-ветке `task/`, созданной от актуальной основной ветки `master`/`main`. Например, `task/prepare-release-0-9-3` — имя ветки, а не путь каталога. +- Подготовленные документы включаются в основную ветку через одобренный запрос на слияние (Pull Request, PR). Только после этого из выбранного актуального коммита основной ветки создаются релизная ветка и, после обязательных проверок, тег: [процесс релиза](../release.md#выпуск-релиза). +- Для срочного исправления от рабочего тега файлы готовятся и включаются в выбранную ветку патч-релиза по [отдельному сценарию](../release.md#hotfix-и-patch-release). Само повышение версии на `patch` не делает обычный релиз срочным исправлением. - Минимально обязательный файл в каталоге релиза: `release-plan.md`. - Файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. - План описывает предстоящие действия. Фактические результаты проверок и выкладки записываются в комментариях к PR подготовки релиза, а не заранее в плане. diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 2d6e6e5..c990be7 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -8,8 +8,11 @@ - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: - Линия релиза: `release/x.y` -- Рабочая ветка подготовки: `task/`, созданная от релизной ветки `release/x.y` -- PR подготовки релиза в релизную ветку `release/x.y`: +- Сценарий: обычный релиз из основной ветки / срочное исправление от рабочего тега (указать одно) +- Основная ветка проекта: `master` или `main` (указать фактическую) +- База рабочей ветки и цель PR: для обычного релиза — основная ветка; для срочного исправления — согласованная ветка патч-релиза +- Рабочая ветка подготовки: `task/` +- PR подготовки релиза: - Ответственный: - Плановая дата deploy: @@ -35,8 +38,10 @@ ## План проверок перед выкладкой - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов -- Убедиться, что этот план и остальные релизные файлы включены через одобренный PR до создания тега -- Убедиться, что тег указывает на выбранный коммит релиза после слияния и опубликован в `origin` +- Убедиться, что этот план, остальные релизные файлы и исправления обычного релиза включены через одобренные PR в основную ветку до создания релизной ветки и тега +- Для обычного релиза проверить, что релизная ветка создана от согласованного актуального коммита основной ветки и тег отмечает этот же коммит; изменений, существующих только в релизной ветке, нет +- Для срочного исправления проверить состав и коммит по отдельному сценарию в Git-регламенте проекта, а также план возврата исправления в основную ветку +- Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: - Проверить готовность миграций, порядок их применения и риск окна несовместимости: - Команды проверки работоспособности (health-check) и ожидаемые результаты: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index d84bd82..f6e919b 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 15:05:35 (1789139135) +completed: 2026-09-11 15:36:14 (1789140974) cancelled: value: V2 complexity: C2 @@ -48,9 +48,9 @@ status: done ## 3. Требования, MoSCoW (Requirements) ### 🔴 Обязательно (Must Have) -- [x] Для рабочей ветки стабилизации явно использовать активную `release/x.y` как базу и цель PR; синхронизировать с выбранной базой. +- [x] По уточнению пользователя обычный релиз готовить в рабочей ветке от актуальной основной ветки `master`/`main`, направлять PR туда же и включать код и релизные файлы до выпуска. Подготовку срочного исправления от рабочего тега описывать отдельно. - [x] Сохранить запрет прямых коммитов в `master` и `release/*`; подготовку релизных файлов выполнять в рабочей ветке через PR. -- [x] Создавать и публиковать конкретный релизный тег только на проверенном слитом коммите целевой ветки; не отправлять все локальные теги. +- [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. - [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. - [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. @@ -81,7 +81,7 @@ git diff --check ### Результат выполнения - Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. -- Релизные файлы готовятся в рабочей ветке `task/`, созданной от релизной ветки `release/x.y`, и проходят PR с окончательным одобрением. Конкретный неизменяемый тег создаётся на согласованном коммите релиза после слияния. Автокоммит, автотег и публикация всех тегов исключены. +- Релизные файлы обычного релиза готовятся в рабочей ветке `task/` от актуального `master`/`main` и включаются туда через одобренный PR. Релизная ветка и неизменяемый тег фиксируют выбранный актуальный коммит основной ветки. Автокоммит, автотег и публикация всех тегов исключены; срочное исправление от рабочего тега описано отдельно. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Параметры `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`. @@ -103,6 +103,15 @@ git diff --check - Повторно выполнены `composer validate --strict`, `git diff --check`, установка в `/tmp/git-workflow-revision-init.uTaXxW` и повторная установка: 11 документов скопированы, затем 11 пропущены; копия полностью совпадает с исходниками. - После завершения правок задача снова оформляется в `done` до запроса окончательного одобрения. Текущее состояние автоматических проверок доступно в PR #10; предыдущие результаты CI относятся к предыдущей редакции. +### Уточнение источника обычного релиза + +- Пользователь указал риск выпуска кода, отсутствующего в основной ветке, и подтвердил исправление модели сообщением «надо поправить». Прежнее требование готовить обычный релиз в релизной ветке заменено, а не оставлено альтернативным порядком. +- Код, исправления и релизные файлы сначала включаются в `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. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. @@ -123,3 +132,4 @@ git diff --check | 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 в основную ветку, фиксация её коммита, отдельный сценарий срочного исправления | From c03334d008e4320a3b8bc0acc94cc38c193d0cb7 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Fri, 11 Sep 2026 23:00:04 +0700 Subject: [PATCH 05/40] =?UTF-8?q?docs(workflow):=20trim=20redundant=20expl?= =?UTF-8?q?anations=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=B8?= =?UTF-8?q?=D0=B7=D0=B1=D1=8B=D1=82=D0=BE=D1=87=D0=BD=D1=8B=D0=B5=20=D0=BF?= =?UTF-8?q?=D0=BE=D1=8F=D1=81=D0=BD=D0=B5=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 7 ++- docs/git-workflow/commits.md | 1 - docs/git-workflow/deploy.md | 2 +- docs/git-workflow/pull-request.md | 10 ++--- docs/git-workflow/release-checklists.md | 6 +-- docs/git-workflow/release.md | 43 ++++++++----------- docs/git-workflow/releases/index.md | 7 ++- .../templates/release-plan.template.md | 6 +-- ...K-docs-align-workflow-instructions.todo.md | 3 +- 9 files changed, 38 insertions(+), 47 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index dbc8a75..03d8bc4 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -55,18 +55,17 @@ git pull --ff-only origin master git switch -c task/ ``` -Только для подготовки файлов **срочного исправления от рабочего тега** рабочая ветка может создаваться от выбранной ветки патч-релиза; PR направляется в неё по [отдельному сценарию](release.md#hotfix-и-patch-release). Это не источник обычного релиза, даже если его версия повышается только на `patch`. +Для подготовки файлов срочного исправления база и цель PR — выбранная ветка патч-релиза: [отдельный сценарий](release.md#hotfix-и-patch-release). ### Release branch Для обычного релиза создаётся от согласованного актуального коммита основной ветки **после включения в неё кода и релизных файлов через PR**. Точная последовательность и команды — в [процессе релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки). Правила для `release/x.y`: -- предыдущая релизная ветка не используется как база нового обычного релиза; -- тег обычного релиза отмечает выбранный коммит, уже присутствующий в истории основной ветки; +- тег обычного релиза отмечает выбранный коммит основной ветки; - найденные ошибки сначала исправляются через PR в основную ветку, затем состав релиза выбирается заново из неё; - новые задачи продолжают включаться в основную ветку и не меняют зафиксированный состав автоматически; -- занятое имя ветки не разрешает принудительную перезапись: сначала завершается предыдущая линия по правилам ниже. +- если имя ветки занято, сначала завершается предыдущая линия; принудительная перезапись запрещена. ### Hotfix branch diff --git a/docs/git-workflow/commits.md b/docs/git-workflow/commits.md index 8570ecc..abe6da4 100644 --- a/docs/git-workflow/commits.md +++ b/docs/git-workflow/commits.md @@ -81,7 +81,6 @@ Scope указывает на область изменения, в качест - Не смешивай в одном коммите поведение и форматирование. - Не смешивай `move/rename` и `refactor/behavior change` в одном коммите. - Используй `git commit -m ...` без генераторов, в том числе для релизных коммитов. -- Этот документ — единый источник правил подготовки сообщений; интерактивный помощник не требуется. ## Примеры diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 728747c..369c368 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,7 +28,7 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Для обычного релиза включить код, исправления и релизные файлы через одобренные PR (запросы на слияние) в основную ветку `master`/`main`. Рабочая ветка подготовки создаётся от неё, не от предыдущей релизной ветки. +1. Для обычного релиза включить код, исправления и релизные файлы через одобренные PR (запросы на слияние) в основную ветку `master`/`main`. 2. Зафиксировать согласованный актуальный коммит основной ветки, создать от него релизную ветку `release/x.y` и после обязательных проверок, включая `make tests-e2e`, опубликовать тег `vX.Y.Z` на том же коммите по [процессу релиза](release.md#выпуск-релиза). Срочное исправление от рабочего тега готовится по [отдельному сценарию](release.md#hotfix-и-patch-release). 3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. 4. Провести post-check: основные user-flow, логи, метрики. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 363492d..6b0a08d 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -38,8 +38,8 @@ package: prikotov/git-workflow ## Выбор base branch -- Рабочая ветка `task/` для обычной разработки, исправлений перед релизом и подготовки релизных файлов создаётся от актуальной основной ветки `master` или `main`; PR направляется туда же. Далее `master` означает основную ветку проекта. -- Ветка `release/x.y` обычного релиза создаётся только после включения кода и релизных файлов в основную ветку. PR подготовки обычного релиза не направляется в предыдущую релизную ветку. +- Для обычной разработки и подготовки релиза база ветки `task/` и цель PR — актуальная основная ветка `master` или `main`. Далее она обозначается как `master`. +- Релизная ветка создаётся после включения кода и релизных файлов в основную ветку: [процесс релиза](release.md#выпуск-релиза). - Подготовка файлов срочного исправления от рабочего тега — исключение: рабочая ветка создаётся от выбранной ветки патч-релиза, PR направляется в неё по [отдельному сценарию](release.md#hotfix-и-patch-release). - Рабочая ветка срочного исправления `hotfix/x.y.z-` направляется через PR в релизную ветку текущей рабочей версии, если та ещё активна. Дополнительно обязателен возврат изменений (merge-back) в ветку `master`. - Если релизная ветка текущей рабочей версии уже закрыта, целевую ветку патч-релиза согласуй с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска патч-релиза. @@ -58,7 +58,7 @@ package: prikotov/git-workflow - Сделай self-review: [Ревью кода (Code Review)](code-review.md). - Используй CLI-инструменты: `git`, `gh`. - Сделай push: `git push -u origin HEAD`. -- Создай PR с явной базой: `gh pr create --base --head "$(git branch --show-current)"`; `` — основная ветка `master`/`main` для обычной разработки и релиза либо согласованная ветка срочного исправления. +- Создай PR с [выбранной базой](#выбор-base-branch): `gh pr create --base --head "$(git branch --show-current)"`. - Тело PR передавай через `gh pr create --body-file`. - Предпочитай `--body-file -` (stdin) или файл в `tmp/`. - Связь задачи с PR и переходы статусов веди по установленным в проекте правилам `todo-md`. Формат полей и механика задач не определяются этим пакетом. @@ -97,7 +97,7 @@ package: prikotov/git-workflow ## Подготовка PR - Заверши все изменения в PR-ветке до запроса окончательного одобрения (approve), включая релизные файлы и служебные обновления задачи по правилам `todo-md` проекта. -- Если PR завершает реализацию задачи, переведи её в `done` до окончательного одобрения и отправь изменения в ту же ветку. Формат полей, перенос файла и обновление ссылок определяет `todo-md`; момент завершения относительно одобрения определяет этот Git-процесс. +- Если PR завершает реализацию задачи, оформи `done` по правилам `todo-md` проекта и опубликуй изменения до окончательного одобрения. - PR только с постановкой не завершает реализацию поставленной задачи: она остаётся в `todo` или `backlog` по правилам проекта. Если работа над постановкой ведётся отдельной задачей, заверши только её. - После последнего push дождись зелёного CI и выполни обязательные проверки окончательного состояния PR. - Запроси одобрение пользователя именно на это состояние PR. @@ -113,7 +113,7 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- Возврат срочного исправления (merge-back) в основную ветку выполняй отдельным PR из рабочей ветки. Обычный релиз не должен ждать такого возврата после выпуска: его код и релизные файлы включаются в основную ветку заранее. +- Возврат срочного исправления (merge-back) в основную ветку выполняй отдельным PR. Обычный релиз возврата не требует: его изменения уже включены в основную ветку. ## После merge diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 275921d..87a4462 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -10,7 +10,7 @@ package: prikotov/git-workflow Этот чеклист относится к обычному релизу, включая обычное повышение `patch`. Срочное исправление от рабочего тега описано отдельно ниже. Основная ветка проекта — `master` или `main`. -- Согласован состав актуальной основной ветки, а не выбран набор изменений из предыдущей релизной ветки. +- Согласован состав релиза из актуальной основной ветки. - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. @@ -20,7 +20,7 @@ package: prikotov/git-workflow - Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. - Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в основную ветку подтверждено и выполнено через GitHub. - После включения кода и релизных файлов зафиксирован полный идентификатор (SHA) согласованного актуального коммита основной ветки. Возможные изменения, вошедшие после PR подготовки, учтены; после проверок нет непроверенных изменений кода, зависимостей или конфигурации. -- Ветка `release/x.y` создана от этого коммита по [процессу релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки), не от предыдущей релизной ветки. Коммит тега обычного релиза принадлежит истории основной ветки; изменений только в релизной ветке нет. +- Ветка `release/x.y` создана от этого коммита по [процессу релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки). - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления @@ -31,7 +31,7 @@ package: prikotov/git-workflow - Зафиксирован план включения исправления в выбранную ветку патч-релиза и возврата изменений в ветку `master`. - Исправление проходит PR в релизную ветку текущей рабочей версии. Если она закрыта, целевая ветка патч-релиза согласована с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). - Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки успешны. -- Релизные файлы проходят отдельный PR из рабочей ветки `task/`, созданной от выбранной ветки исправления. Тег отмечает согласованный коммит после слияния в неё по [сценарию срочного исправления](release.md#hotfix-и-patch-release), а не текущий коммит основной ветки с ещё не выпущенными изменениями. +- Релизные файлы включены отдельным PR из ветки `task/` от выбранной ветки исправления. Тег отмечает согласованный коммит слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). ## Чеклист выкладки diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 352a966..4e00d49 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -9,13 +9,13 @@ package: prikotov/git-workflow ## Модель релизов - Код, исправления и релизные файлы обычного релиза сначала включаются в основную ветку через запросы на слияние (Pull Request, PR). -- Рабочая ветка подготовки `task/` создаётся от актуальной основной ветки; PR направляется туда же, а не в предыдущую релизную ветку. +- Ветка подготовки `task/` создаётся от актуальной основной ветки; PR направляется туда же. - После включения релизных файлов фиксируется актуальный коммит основной ветки. От него создаётся ветка `release/x.y`, и этот же коммит отмечается тегом после обязательных проверок. -- В обычном релизе не должно быть изменений, отсутствующих в основной ветке. Релизная ветка фиксирует выбранный состав, а не служит независимой веткой разработки. +- Релизная ветка фиксирует состав обычного релиза; самостоятельная разработка в ней запрещена. - Прямые правки и коммиты в целевых ветках `master`, `main` и `release/*` запрещены. - Рабочая среда всегда разворачивается по **конкретному тегу**, а не по последнему коммиту ветки. - Одновременно поддерживается только одна активная релизная ветка `release/x.y`. -- Срочное исправление от рабочего тега — отдельное исключение: см. [Hotfix и patch release](#hotfix-и-patch-release). Оно не меняет источник обычных релизов. +- Срочное исправление от рабочего тега — исключение: [Hotfix и patch release](#hotfix-и-patch-release). ## SemVer и линии релиза @@ -36,8 +36,7 @@ package: prikotov/git-workflow Тип релиза определяется по истории Conventional Commits: `fix` требует `patch`, `feat` — `minor`, а `BREAKING CHANGE` или `!` — `minor` при текущей версии `0.x` и `major` начиная с `1.0.0`. Выбранную версию явно передавайте генератору; его автоматическое повышение не заменяет эти правила, особенно для `0.x`. -- `patch` сохраняет номера `major.minor`, но не предписывает брать код из предыдущей релизной ветки. Обычный патч-релиз также выпускается из актуальной основной ветки. -- `minor` и `major` меняют номер релизной линии `x.y`. Выбор версии и выбор источника кода — разные решения. +Обычный патч-релиз также выпускается из актуальной основной ветки. `patch` сохраняет номер линии `x.y`, а `minor` и `major` меняют его. ## Подготовка коммитов @@ -55,22 +54,18 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## Release cut -Фиксация состава релиза (release cut) выполняется **после включения кода и релизных файлов в основную ветку**, а не перед их подготовкой. Порядок выбора коммита и создания ветки приведён в разделе [«Выпуск релиза»](#выпуск-релиза). +Состав релиза фиксируется (release cut) после включения кода и релизных файлов в основную ветку: [порядок выпуска](#выпуск-релиза). После фиксации: - новые задачи продолжают включаться в основную ветку, но не попадают в уже выбранный состав автоматически; -- найденные ошибки исправляются через PR в основную ветку; затем заново согласуется коммит релиза из неё, а не добавляется код только в релизную ветку; +- найденные ошибки исправляются через PR в основную ветку; затем заново согласуется коммит релиза; - исправление уже работающей версии от её тега выполняется отдельно по [правилам срочного исправления](#hotfix-и-patch-release). ## План релиза -Для каждого релиза в рабочей ветке подготовки, до одобрения PR и создания тега, создаётся документ `docs/releases/vX.Y.Z/release-plan.md`. +До одобрения PR подготовки создайте `docs/releases/vX.Y.Z/release-plan.md` по [шаблону](./templates/release-plan.template.md). Без заполненного плана выкладка запрещена. -- место хранения: `docs/releases/`; -- шаблон: [release-plan.template.md](./templates/release-plan.template.md). -- без заполненного `release-plan.md` deploy не начинается. - -Для обычного релиза — в рабочей ветке `task/`, созданной от актуальной основной ветки, после выбора версии (релизная ветка и тег ещё не созданы). Для срочного исправления источник указан в [отдельном сценарии](#hotfix-и-patch-release): +В ветке подготовки, после выбора версии: ```bash mkdir -p docs/releases/vX.Y.Z @@ -84,7 +79,7 @@ cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/rel - проверки после deploy; - план действий при проблеме после релиза через hotfix или patch release. -План описывает предстоящие действия, а не подтверждает их выполнение. Фактические результаты проверок и выкладки фиксируйте в комментариях к PR подготовки релиза; не дописывайте их в одобренную ветку и не перемещайте тег ради обновления отчёта. +Результаты проверок и выкладки фиксируйте в комментариях к PR подготовки, не меняя одобренную ветку или тег. ## Работа с CHANGELOG @@ -123,19 +118,18 @@ git switch -c task/prepare-release-x-y-z 1. Выберите версию по SemVer, подготовьте `CHANGELOG.md`, файлы версий и `docs/releases/vX.Y.Z/release-plan.md` в этой ветке. 2. Проверьте diff и создайте коммит вручную по [commits.md](commits.md). -3. Откройте PR из рабочей ветки подготовки в основную ветку по [правилам PR](pull-request.md). Исправления и релизные файлы должны попасть туда до выпуска; рабочая ветка синхронизируется с этой же основной веткой. +3. Синхронизируйте рабочую ветку с основной и откройте PR в неё по [правилам PR](pull-request.md). 4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Перед релизом выполните `make check` и обязательно запустите сквозные тесты командой `make tests-e2e`; дождитесь успешного завершения. Проектные исключения для `make check` не отменяют предрелизный запуск сквозных тестов. 5. Дождитесь успешных автоматических проверок PR (CI), одобрения окончательного состояния PR и подтверждения слияния пользователем; выполните слияние через GitHub. Если после одобрения нужны изменения, следуйте [порядку повторного одобрения](pull-request.md#подготовка-pr). ### 2. Выбор коммита и создание релизной ветки - После слияния PR получите актуальное состояние основной ветки и согласуйте её текущий коммит как состав релиза. Если после PR подготовки туда вошли другие изменения, проверьте весь получившийся состав и соответствие релизных файлов, а не только исходный PR. -- Зафиксируйте полный идентификатор (SHA) выбранного коммита основной ветки. Нельзя выбирать коммит, существующий только в рабочей или предыдущей релизной ветке. -- Убедитесь, что после обязательных проверок не появились непроверенные изменения кода, зависимостей или конфигурации. Если появились — проверьте их по правилам проекта. Новый идентификатор коммита после слияния сам по себе не требует повторного запуска всех проверок или отдельного CI после слияния; обязательный предрелизный запуск `make tests-e2e` сохраняется. -- Если нужны исправления — проведите новый PR из рабочей ветки в основную ветку, затем заново согласуйте состав релиза из неё. Не добавляйте исправления только в релизную ветку. -- Более поздние изменения основной ветки не подменяют уже зафиксированный коммит автоматически. +- Зафиксируйте полный идентификатор (SHA) выбранного коммита основной ветки. +- Проверьте изменения кода, зависимостей и конфигурации, внесённые после обязательных проверок. Новый SHA после слияния сам по себе не требует полного повторного прогона или отдельного CI. +- Если нужны исправления — включите их через новый PR в основную ветку и заново согласуйте коммит релиза. -Перед созданием ветки убедитесь, что имя `release/x.y` свободно локально и в `origin`. Если оно занято, не берите прежнюю ветку за источник нового обычного релиза и не перезаписывайте её принудительно: сначала завершите предыдущую линию по [правилам веток](branches.md#завершение). После исправлений уже выбранного состава также сначала завершите работу с прежней релизной веткой; новый состав берётся из основной ветки. Это не разрешает менять опубликованные теги. +Имя `release/x.y` должно быть свободно локально и в `origin`. Если оно занято, в том числе после пересмотра состава релиза, сначала завершите предыдущую линию по [правилам веток](branches.md#завершение). Принудительная перезапись ветки запрещена. Проверьте, что выбранный коммит входит в историю основной ветки, и создайте от него релизную ветку. Замените `VERIFIED_MAIN_SHA` полным согласованным идентификатором, а `x.y` — номером линии: @@ -147,11 +141,11 @@ git fetch origin && git push -u origin release/x.y ``` -Если получение актуальных данных, проверка принадлежности основной ветке или создание ветки завершается ошибкой, выпуск останавливается. +При ошибке выпуск останавливается. ### 3. Создание и публикация тега -После обязательных проверок и разрешения на выпуск создайте тег **на зафиксированном коммите**, а не на текущем конце релизной ветки. Для обычного релиза это выбранный коммит основной ветки из шага 2; для срочного исправления — коммит, определённый в [отдельном сценарии](#hotfix-и-patch-release). В примере замените `VERIFIED_RELEASE_SHA` полным идентификатором, а `X.Y.Z` — выбранной версией: +После обязательных проверок и разрешения на выпуск создайте тег **на зафиксированном коммите** из шага 2 либо [сценария срочного исправления](#hotfix-и-patch-release). Подставьте его полный SHA в `VERIFIED_RELEASE_SHA`, выбранную версию — в `X.Y.Z`: ```bash release_commit=VERIFIED_RELEASE_SHA @@ -182,10 +176,10 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md 2. Создайте рабочую ветку срочного исправления `hotfix/x.y.z-` от этого тега. 3. Исправьте проблему и проведите обязательные проверки. 4. Включите исправление через одобренный PR в релизную ветку `release/x.y`. -5. Подготовьте файлы срочного патч-релиза `vX.Y.(Z+1)` в рабочей ветке `task/`, созданной от этой релизной ветки. Включите их через одобренный PR в ту же ветку. После обязательных проверок, включая `make tests-e2e`, зафиксируйте коммит результата слияния и используйте [порядок публикации тега](#3-создание-и-публикация-тега). Этот экстренный сценарий не требует брать текущую основную ветку: в ней могут находиться ещё не выпущенные изменения. +5. Подготовьте файлы патч-релиза `vX.Y.(Z+1)` в ветке `task/` от этой релизной ветки и включите их туда через одобренный PR. После обязательных проверок, включая `make tests-e2e`, зафиксируйте коммит слияния и [опубликуйте тег](#3-создание-и-публикация-тега). 6. Верните изменения срочного исправления в ветку `master` отдельным PR из рабочей ветки. -Если релизная ветка текущей рабочей версии уже закрыта, срочное исправление всё равно начинается от её тега. До открытия PR согласуйте целевую ветку патч-релиза с пользователем; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска. Эта инструкция не предписывает закрывать другую активную релизную ветку или включать в патч-релиз изменения следующей версии. +Если релизная ветка рабочей версии закрыта, до открытия PR согласуйте целевую ветку патч-релиза с пользователем. Не подставляйте ветку следующей версии; закрытие другой активной линии этот сценарий не предписывает. Верните исправление в `master` отдельным PR сразу после выпуска. ## Recovery Policy @@ -196,7 +190,6 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Рекомендации команды -- Перед фиксацией релиза проверьте состав актуальной основной ветки: нельзя исключать из обычного релиза её изменения, незаметно переключаясь на предыдущую релизную ветку. - Для 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 79df0ff..1c0d542 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -13,12 +13,11 @@ package: prikotov/git-workflow ## Правила -- Для обычного релиза каталог `docs/releases/vX.Y.Z/` и его файлы создаются в рабочей Git-ветке `task/`, созданной от актуальной основной ветки `master`/`main`. Например, `task/prepare-release-0-9-3` — имя ветки, а не путь каталога. -- Подготовленные документы включаются в основную ветку через одобренный запрос на слияние (Pull Request, PR). Только после этого из выбранного актуального коммита основной ветки создаются релизная ветка и, после обязательных проверок, тег: [процесс релиза](../release.md#выпуск-релиза). -- Для срочного исправления от рабочего тега файлы готовятся и включаются в выбранную ветку патч-релиза по [отдельному сценарию](../release.md#hotfix-и-patch-release). Само повышение версии на `patch` не делает обычный релиз срочным исправлением. +- Релизные документы `docs/releases/vX.Y.Z/` готовятся в ветке `task/` от актуальной `master`/`main` и включаются туда через одобренный запрос на слияние (Pull Request, PR) до создания релизной ветки и тега: [процесс релиза](../release.md#выпуск-релиза). +- Для срочного исправления от рабочего тега используется [отдельный порядок подготовки](../release.md#hotfix-и-patch-release). - Минимально обязательный файл в каталоге релиза: `release-plan.md`. - Файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. -- План описывает предстоящие действия. Фактические результаты проверок и выкладки записываются в комментариях к PR подготовки релиза, а не заранее в плане. +- Результаты проверок и выкладки записываются в комментариях к PR подготовки релиза. - Для срочного исправления (hotfix) и патч-релиза (patch release) создаётся отдельный каталог с номером новой версии. ## Шаблон diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index c990be7..62818ee 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,6 +1,6 @@ # План релиза vX.Y.Z -Этот документ заполняется до одобрения PR (запроса на слияние) подготовки релиза и создания тега. Здесь описываются будущие действия и критерии их успешности. Фактические результаты проверок и выкладки фиксируются в комментариях к этому PR, без изменения одобренной ветки или тега. +Заполните план до одобрения PR (запроса на слияние) подготовки релиза. Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. ## Метаданные @@ -9,7 +9,7 @@ - Обоснование выбранной версии: - Линия релиза: `release/x.y` - Сценарий: обычный релиз из основной ветки / срочное исправление от рабочего тега (указать одно) -- Основная ветка проекта: `master` или `main` (указать фактическую) +- Основная ветка: `master` / `main` - База рабочей ветки и цель PR: для обычного релиза — основная ветка; для срочного исправления — согласованная ветка патч-релиза - Рабочая ветка подготовки: `task/` - PR подготовки релиза: @@ -39,7 +39,7 @@ - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов - Убедиться, что этот план, остальные релизные файлы и исправления обычного релиза включены через одобренные PR в основную ветку до создания релизной ветки и тега -- Для обычного релиза проверить, что релизная ветка создана от согласованного актуального коммита основной ветки и тег отмечает этот же коммит; изменений, существующих только в релизной ветке, нет +- Для обычного релиза проверить, что релизная ветка и тег указывают на согласованный актуальный коммит основной ветки - Для срочного исправления проверить состав и коммит по отдельному сценарию в Git-регламенте проекта, а также план возврата исправления в основную ветку - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index f6e919b..5184beb 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 15:36:14 (1789140974) +completed: 2026-09-11 15:58:21 (1789142301) cancelled: value: V2 complexity: C2 @@ -133,3 +133,4 @@ git diff --check | 2026-09-11 | Лид (pi) | Реализация и независимое ревью завершены; PR #10 опубликован, CI успешен, задача подготовлена к приёмке | | 2026-09-11 | Технический писатель (pi) | Повторная личная вычитка по замечаниям пользователя: исправлены терминология, проверки релиза, сценарий срочного исправления и шаблон плана; проверки повторены | | 2026-09-11 | Технический писатель (pi) | По уточнению пользователя обычный релиз переведён на источник master/main: подготовка через PR в основную ветку, фиксация её коммита, отдельный сценарий срочного исправления | +| 2026-09-11 | Технический писатель (pi) | По запросу пользователя убраны пояснение «имя ветки, а не путь», повторы и многословные оговорки в инструкциях, чеклистах и шаблоне; правила сохранены | From 575997086fb57207111a250390afeaad0bd6f532 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 06:33:52 +0700 Subject: [PATCH 06/40] =?UTF-8?q?docs(workflow):=20restore=20working=20rel?= =?UTF-8?q?ease=20branches=20/=20=D0=B2=D0=B5=D1=80=D0=BD=D1=83=D1=82?= =?UTF-8?q?=D1=8C=20=D1=80=D0=B0=D0=B1=D0=BE=D1=87=D0=B8=D0=B5=20=D1=80?= =?UTF-8?q?=D0=B5=D0=BB=D0=B8=D0=B7=D0=BD=D1=8B=D0=B5=20=D0=B2=D0=B5=D1=82?= =?UTF-8?q?=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 38 ++++---- docs/git-workflow/deploy.md | 4 +- docs/git-workflow/pull-request.md | 23 +++-- docs/git-workflow/release-checklists.md | 16 ++-- docs/git-workflow/release.md | 86 ++++++++----------- docs/git-workflow/releases/index.md | 3 +- .../templates/release-plan.template.md | 11 +-- ...K-docs-align-workflow-instructions.todo.md | 25 ++++-- 8 files changed, 102 insertions(+), 104 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 03d8bc4..a55dff4 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -17,15 +17,15 @@ package: prikotov/git-workflow - `master` или `main` — основная ветка разработки и источник обычных релизов. В примерах ниже используется `master`; для проекта с `main` замените имя в командах. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. -- `release/x.y` — ветка, фиксирующая выбранный коммит основной ветки для обычного релиза; самостоятельная разработка в ней не ведётся. Исключение — отдельный сценарий срочного исправления рабочей версии. +- `release/x.y` — рабочая ветка финализации релиза от актуальной основной ветки; результат включается в основную ветку через PR. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки. - Одновременно поддерживается только одна активная `release/x.y`. ## Общие правила -- Запрещены прямые правки в `master`. -- Запрещены прямые правки в `release/*`. +- Изменения в `master`/`main` включаются только через PR. +- В `task/*`, `release/*` и `hotfix/*` работают и коммитят по запросу пользователя. Входящие PR в `release/*` не используются. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. @@ -47,7 +47,7 @@ package: prikotov/git-workflow ### Task branch -Для обычной разработки, исправлений перед релизом, документации и подготовки релизных файлов база и цель PR — основная ветка `master` (либо `main`). +Для обычных задач база и цель PR — основная ветка `master` (либо `main`). Документы будущего релиза можно дополнять в этих же задачах. ```bash git switch master @@ -55,17 +55,15 @@ git pull --ff-only origin master git switch -c task/ ``` -Для подготовки файлов срочного исправления база и цель PR — выбранная ветка патч-релиза: [отдельный сценарий](release.md#hotfix-и-patch-release). - ### Release branch -Для обычного релиза создаётся от согласованного актуального коммита основной ветки **после включения в неё кода и релизных файлов через PR**. Точная последовательность и команды — в [процессе релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки). +Создаётся от актуальной основной ветки при начале финализации выпуска: [процесс релиза](release.md#1-финализация-в-релизной-ветке). Правила для `release/x.y`: -- тег обычного релиза отмечает выбранный коммит основной ветки; -- найденные ошибки сначала исправляются через PR в основную ветку, затем состав релиза выбирается заново из неё; -- новые задачи продолжают включаться в основную ветку и не меняют зафиксированный состав автоматически; -- если имя ветки занято, сначала завершается предыдущая линия; принудительная перезапись запрещена. +- необходимые исправления, версии и итоговые релизные документы коммитятся в этой ветке; +- PR направляется из `release/x.y` в основную ветку и включается до публикации тега; +- обычные задачи продолжают идти в основную ветку; перед окончательным одобрением релизная ветка синхронизируется с ней; +- для уже начатого выпуска используется существующая ветка; перед новым выпуском предыдущая линия завершается, принудительная перезапись запрещена. ### Hotfix branch @@ -76,20 +74,18 @@ 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.md#hotfix-и-patch-release). ## Синхронизация -- Рабочая ветка обычной задачи или подготовки обычного релиза синхронизируется с основной веткой `master`/`main`, в которую направляется PR. -- Рабочая ветка подготовки срочного патч-релиза синхронизируется с выбранной веткой этого исправления. Не подтягивай туда ещё не выпущенные изменения основной ветки. -- Локальная релизная ветка обновляется только из одноимённой ветки `origin` через `--ff-only`. Зафиксированный состав обычного релиза не обновляется из основной ветки автоматически. -- Изменения из рабочей ветки `hotfix/x.y.z-` должны попасть в выбранную ветку патч-релиза и в ветку `master`; целевая ветка определяется по [правилам срочного исправления](release.md#hotfix-и-patch-release). +- `task/*` и `release/*` синхронизируются с основной веткой `master`/`main` до окончательного одобрения PR. +- До выпуска `hotfix/*` не подтягивай в неё ещё не выпущенные изменения основной ветки. После выпуска подготовь возврат исправления через PR в основную ветку. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. -В рабочей ветке выбери базу и получи её актуальное состояние: +В `task/*` или `release/*` получи актуальное состояние основной ветки: ```bash -base=master # Для проекта с main: base=main. Для срочного патч-релиза — согласованная ветка исправления. +base=master # Для проекта с main: base=main. git fetch origin ``` @@ -109,6 +105,6 @@ git rebase "origin/$base" ## Завершение -- После merge PR рабочую ветку нужно удалить локально и в `origin`. -- Релизную ветку можно удалить после завершения работы с выбранным составом и закрытия линии. Для выпущенной версии сохраняется неизменяемый тег; для отменённого кандидата тег не создаётся. При срочном исправлении сначала завершается возврат изменений в основную ветку. Обычный релиз отдельного возврата не требует: его изменения уже включены туда до выпуска. -- Hotfix branch удаляется сразу после merge-back в целевые ветки. +- `task/*` удаляется локально и в `origin` после слияния PR. +- `release/*` сохраняется до завершения выпуска и закрытия линии; её изменения должны быть включены в основную ветку. Для выпущенной версии остаётся неизменяемый тег; отменённый кандидат не тегируется. +- `hotfix/*` удаляется после выпуска и включения исправления в основную ветку. diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 369c368..055388f 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,8 +28,8 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Для обычного релиза включить код, исправления и релизные файлы через одобренные PR (запросы на слияние) в основную ветку `master`/`main`. -2. Зафиксировать согласованный актуальный коммит основной ветки, создать от него релизную ветку `release/x.y` и после обязательных проверок, включая `make tests-e2e`, опубликовать тег `vX.Y.Z` на том же коммите по [процессу релиза](release.md#выпуск-релиза). Срочное исправление от рабочего тега готовится по [отдельному сценарию](release.md#hotfix-и-patch-release). +1. Финализировать обычный релиз в `release/x.y` от актуальной `master`/`main`: актуализировать документы, подготовить версии и необходимые исправления. +2. Выполнить обязательные проверки, включая `make tests-e2e`, и включить одобренный PR (запрос на слияние) из `release/x.y` в основную ветку. Проверить результат слияния и опубликовать тег по [процессу релиза](release.md#выпуск-релиза). Срочное исправление от рабочего тега готовится по [отдельному сценарию](release.md#hotfix-и-patch-release). 3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. 4. Провести post-check: основные user-flow, логи, метрики. 5. При проблеме остановить rollout и выпустить hotfix или patch release. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 6b0a08d..1d5e5c7 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)** — предложенный набор изменений из рабочей ветки в основную (`master` или `main`), проходящий проверки и `Code Review`. ## Границы ответственности @@ -16,7 +16,7 @@ package: prikotov/git-workflow ## Правила -- Запрещены прямые правки в `master` и `release/*`. +- Изменения в `master`/`main` включаются только через PR. В рабочих ветках `task/*`, `release/*` и `hotfix/*` коммиты разрешены по запросу пользователя. - Одна задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. @@ -38,11 +38,11 @@ package: prikotov/git-workflow ## Выбор base branch -- Для обычной разработки и подготовки релиза база ветки `task/` и цель PR — актуальная основная ветка `master` или `main`. Далее она обозначается как `master`. -- Релизная ветка создаётся после включения кода и релизных файлов в основную ветку: [процесс релиза](release.md#выпуск-релиза). -- Подготовка файлов срочного исправления от рабочего тега — исключение: рабочая ветка создаётся от выбранной ветки патч-релиза, PR направляется в неё по [отдельному сценарию](release.md#hotfix-и-patch-release). -- Рабочая ветка срочного исправления `hotfix/x.y.z-` направляется через PR в релизную ветку текущей рабочей версии, если та ещё активна. Дополнительно обязателен возврат изменений (merge-back) в ветку `master`. -- Если релизная ветка текущей рабочей версии уже закрыта, целевую ветку патч-релиза согласуй с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза; возврат изменений в ветку `master` выполняется отдельным PR сразу после выпуска патч-релиза. +- Цель PR — основная ветка `master` или `main`. Далее она обозначается как `master`. +- Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. +- Финализация релиза: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. Входящие PR в `release/*` не используются. +- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку. Выпуск и возврат изменений выполняются по [отдельному сценарию](release.md#hotfix-и-patch-release). +- До выпуска срочного исправления не синхронизируй его ветку с основной. Если для слияния нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. ## Обязательные проверки @@ -67,9 +67,9 @@ package: prikotov/git-workflow - Заголовок PR: английский, кратко отражает суть. - Для release и hotfix PR явно укажи: - - release line (`release/x.y`); + - релизную ветку `release/x.y` либо ветку срочного исправления `hotfix/*`; - production tag, который исправляем или выпускаем; - - нужен ли merge-back в `master`; + - порядок выпуска и включения изменений в основную ветку; - какие изменения сознательно **не** входят в этот релиз. - Описание PR включает: - если проект использует `todo-md` и задачи ещё нет — оформи её по установленным в проекте правилам `todo-md`; @@ -113,12 +113,11 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- Возврат срочного исправления (merge-back) в основную ветку выполняй отдельным PR. Обычный релиз возврата не требует: его изменения уже включены в основную ветку. +- PR обычного релиза из `release/*` включается в основную ветку до публикации тега; PR срочного исправления — сразу после его выпуска. ## После merge - После merge PR в `master` переключись на `master` и обнови его: `git pull --ff-only origin master`. -- После слияния PR срочного исправления в релизную ветку оставайся на этой линии только при продолжении работы над исправлением; иначе вернись в основную ветку. -- Удали рабочую ветку локально и в `origin`. +- Удали `task/*` локально и в `origin`. Для `release/*` дождись завершения выпуска и закрытия линии; для `hotfix/*` — выпуска и включения исправления в основную ветку. - Проверь, что рабочее дерево чистое: `git status`. - Предложи пользователю следующую задачу. diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 87a4462..95e4f7c 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -14,13 +14,14 @@ package: prikotov/git-workflow - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. -- Рабочие ветки `task/` для исправлений и подготовки релизных файлов созданы от актуальной основной ветки, синхронизируются с ней и направляются в неё через PR (запросы на слияние). -- `CHANGELOG.md`, файлы версий и заполненный `docs/releases/vX.Y.Z/release-plan.md` подготовлены в рабочей ветке без автоматического коммита и тега. +- Рабочая ветка `release/x.y` создана от актуальной основной ветки по [процессу релиза](release.md#1-финализация-в-релизной-ветке). +- Накопленные в задачах документы проверены и актуализированы; существующий `release-plan.md` сохранён, действия до и после выпуска учтены. +- Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y` вручную, без автоматического тега. +- PR (запрос на слияние) открыт из `release/x.y` в основную ветку; синхронизация завершена до окончательного одобрения. - Все правки, включая служебные обновления задачи, включены до окончательных проверок и одобрения PR. - Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. - Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в основную ветку подтверждено и выполнено через GitHub. -- После включения кода и релизных файлов зафиксирован полный идентификатор (SHA) согласованного актуального коммита основной ветки. Возможные изменения, вошедшие после PR подготовки, учтены; после проверок нет непроверенных изменений кода, зависимостей или конфигурации. -- Ветка `release/x.y` создана от этого коммита по [процессу релиза](release.md#2-выбор-коммита-и-создание-релизной-ветки). +- Зафиксированы SHA одобренной релизной ветки и результата слияния PR. Проверены принадлежность результата основной ветке и совпадение содержимого: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления @@ -28,15 +29,14 @@ package: prikotov/git-workflow - Определён текущий тег релиза на production `vX.Y.Z`. - Рабочая ветка срочного исправления `hotfix/x.y.z-` создана от тега рабочей среды, а не от ветки `master`. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Зафиксирован план включения исправления в выбранную ветку патч-релиза и возврата изменений в ветку `master`. -- Исправление проходит PR в релизную ветку текущей рабочей версии. Если она закрыта, целевая ветка патч-релиза согласована с пользователем по [правилам релиза](release.md#hotfix-и-patch-release). +- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; PR направлен в основную ветку, включение запланировано сразу после выпуска. - Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки успешны. -- Релизные файлы включены отдельным PR из ветки `task/` от выбранной ветки исправления. Тег отмечает согласованный коммит слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +- Проверенное состояние одобрено, выпуск разрешён. Тег отмечает зафиксированный коммит `hotfix/*` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). ## Чеклист выкладки - Выбран опубликованный неизменяемый тег `vX.Y.Z`: для обычного релиза он указывает на согласованный коммит основной ветки, для срочного исправления — на коммит соответствующего патч-релиза. -- Файл плана `docs/releases/vX.Y.Z/release-plan.md` включён через PR и присутствует в версии, отмеченной этим тегом. +- Актуальный `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 4e00d49..b45811c 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -8,11 +8,11 @@ package: prikotov/git-workflow ## Модель релизов -- Код, исправления и релизные файлы обычного релиза сначала включаются в основную ветку через запросы на слияние (Pull Request, PR). -- Ветка подготовки `task/` создаётся от актуальной основной ветки; PR направляется туда же. -- После включения релизных файлов фиксируется актуальный коммит основной ветки. От него создаётся ветка `release/x.y`, и этот же коммит отмечается тегом после обязательных проверок. -- Релизная ветка фиксирует состав обычного релиза; самостоятельная разработка в ней запрещена. -- Прямые правки и коммиты в целевых ветках `master`, `main` и `release/*` запрещены. +- Документы будущего релиза можно создавать и дополнять в рамках обычных задач, до создания релизной ветки. +- Для финализации обычного релиза создаётся рабочая ветка `release/x.y` от актуальной основной ветки. +- Исправления и релизные файлы коммитятся в `release/x.y`. Из неё открывается запрос на слияние (Pull Request, PR) в основную ветку; входящие PR в `release/*` не используются. +- После проверок и одобрения PR включается в основную ветку до публикации тега. Тег отмечает проверенный результат этого слияния. +- Изменения в `master`/`main` включаются только через PR. Коммиты в рабочих ветках `task/*`, `release/*` и `hotfix/*` разрешены по запросу пользователя. - Рабочая среда всегда разворачивается по **конкретному тегу**, а не по последнему коммиту ветки. - Одновременно поддерживается только одна активная релизная ветка `release/x.y`. - Срочное исправление от рабочего тега — исключение: [Hotfix и patch release](#hotfix-и-patch-release). @@ -54,23 +54,15 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## Release cut -Состав релиза фиксируется (release cut) после включения кода и релизных файлов в основную ветку: [порядок выпуска](#выпуск-релиза). +Финализация выпуска начинается с создания `release/x.y` от актуальной основной ветки. В ней уточняются состав релиза, документы и необходимые исправления. -После фиксации: -- новые задачи продолжают включаться в основную ветку, но не попадают в уже выбранный состав автоматически; -- найденные ошибки исправляются через PR в основную ветку; затем заново согласуется коммит релиза; -- исправление уже работающей версии от её тега выполняется отдельно по [правилам срочного исправления](#hotfix-и-patch-release). +До окончательного одобрения синхронизируйте релизную ветку с основной и проверьте весь получившийся состав. После одобрения состав не меняется без повторных проверок и нового одобрения: [правила PR](pull-request.md#подготовка-pr). Окончательный коммит выпуска фиксируется после слияния PR в основную ветку. ## План релиза -До одобрения PR подготовки создайте `docs/releases/vX.Y.Z/release-plan.md` по [шаблону](./templates/release-plan.template.md). Без заполненного плана выкладка запрещена. +Документы в `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/x.y` проверьте полноту, актуальность и соответствие документов составу релиза. Если `release-plan.md` ещё нет, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не заменяйте шаблоном. До одобрения PR план должен быть заполнен. Без него выкладка запрещена. В `release-plan.md` обязательно зафиксируйте: - состав релиза и его границы; @@ -83,7 +75,7 @@ cp docs/git-workflow/templates/release-plan.template.md docs/releases/vX.Y.Z/rel ## Работа с CHANGELOG -Генерируйте файлы только в рабочей ветке подготовки релиза. Если проект использует `marcocesarato/php-conventional-changelog`, документированный вызов без автоматического коммита и тега: +Генерируйте файлы в `release/*`, для срочного исправления — в `hotfix/*`. Если проект использует `marcocesarato/php-conventional-changelog`, документированный вызов без автоматического коммита и тега: ```bash php vendor/bin/conventional-changelog --ver="X.Y.Z" --no-tag --merged @@ -106,42 +98,40 @@ git diff ## Выпуск релиза -### 1. Подготовка файлов через PR +### 1. Финализация в релизной ветке + +Выберите версию по SemVer и создайте `release/x.y` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке. Перед новым выпуском завершите предыдущую линию по [правилам веток](branches.md#завершение); имя должно быть свободно локально и в `origin`, принудительная перезапись запрещена. -Для обычного релиза создайте рабочую ветку подготовки от актуальной основной ветки. Замените `x-y-z` выбранным номером версии: +Замените `x.y` номером линии: ```bash -git switch master -git pull --ff-only origin master -git switch -c task/prepare-release-x-y-z +git switch master && + git pull --ff-only origin master && + git switch -c release/x.y && + git push -u origin release/x.y ``` -1. Выберите версию по SemVer, подготовьте `CHANGELOG.md`, файлы версий и `docs/releases/vX.Y.Z/release-plan.md` в этой ветке. -2. Проверьте diff и создайте коммит вручную по [commits.md](commits.md). -3. Синхронизируйте рабочую ветку с основной и откройте PR в неё по [правилам PR](pull-request.md). -4. Завершите все правки, включая служебные обновления задачи, до окончательных проверок и одобрения. Перед релизом выполните `make check` и обязательно запустите сквозные тесты командой `make tests-e2e`; дождитесь успешного завершения. Проектные исключения для `make check` не отменяют предрелизный запуск сквозных тестов. -5. Дождитесь успешных автоматических проверок PR (CI), одобрения окончательного состояния PR и подтверждения слияния пользователем; выполните слияние через GitHub. Если после одобрения нужны изменения, следуйте [порядку повторного одобрения](pull-request.md#подготовка-pr). - -### 2. Выбор коммита и создание релизной ветки +1. В `release/x.y` подготовьте `CHANGELOG.md`, файлы версий, актуализируйте накопленные документы и внесите необходимые исправления. +2. Проверьте diff и создайте коммиты вручную по [commits.md](commits.md). +3. Откройте PR **из `release/x.y` в основную ветку** по [правилам PR](pull-request.md). +4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните `make check` и обязательный предрелизный запуск `make tests-e2e`; дождитесь успеха. Проектные исключения для `make check` не отменяют сквозные тесты. +5. Зафиксируйте SHA проверенного состояния `release/x.y`. Дождитесь успешных автоматических проверок PR (CI), одобрения и подтверждения слияния пользователем. Выполните слияние через GitHub. Доработки требуют [повторного одобрения](pull-request.md#подготовка-pr). -- После слияния PR получите актуальное состояние основной ветки и согласуйте её текущий коммит как состав релиза. Если после PR подготовки туда вошли другие изменения, проверьте весь получившийся состав и соответствие релизных файлов, а не только исходный PR. -- Зафиксируйте полный идентификатор (SHA) выбранного коммита основной ветки. -- Проверьте изменения кода, зависимостей и конфигурации, внесённые после обязательных проверок. Новый SHA после слияния сам по себе не требует полного повторного прогона или отдельного CI. -- Если нужны исправления — включите их через новый PR в основную ветку и заново согласуйте коммит релиза. +### 2. Проверка коммита выпуска -Имя `release/x.y` должно быть свободно локально и в `origin`. Если оно занято, в том числе после пересмотра состава релиза, сначала завершите предыдущую линию по [правилам веток](branches.md#завершение). Принудительная перезапись ветки запрещена. +После слияния возьмите SHA результата PR в основной ветке и сравните его содержимое с одобренным состоянием `release/x.y`. Более поздние коммиты основной ветки не подменяют этот результат. -Проверьте, что выбранный коммит входит в историю основной ветки, и создайте от него релизную ветку. Замените `VERIFIED_MAIN_SHA` полным согласованным идентификатором, а `x.y` — номером линии: +Подставьте полные SHA результата слияния и одобренной релизной ветки: ```bash -release_commit=VERIFIED_MAIN_SHA +release_commit=VERIFIED_MERGE_SHA +release_head=APPROVED_RELEASE_SHA git fetch origin && git merge-base --is-ancestor "$release_commit" origin/master && - git branch release/x.y "$release_commit" && - git push -u origin release/x.y + git diff --exit-code "$release_head" "$release_commit" -- ``` -При ошибке выпуск останавливается. +При ошибке или различиях выпуск останавливается. Согласуйте изменившийся состав, проверьте новые изменения кода, зависимостей и конфигурации; необходимые доработки включите новым PR из релизной ветки в основную. Новый SHA при неизменном содержимом сам по себе не требует полного повторного прогона или отдельного CI. ### 3. Создание и публикация тега @@ -169,17 +159,15 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Hotfix и patch release -Срочный hotfix не делается от `master`. +Срочное исправление готовится от рабочего тега, без ещё не выпущенных изменений основной ветки: -Если активная релизная ветка соответствует версии в рабочей среде: -1. Определите текущий тег рабочей среды `vX.Y.Z`. -2. Создайте рабочую ветку срочного исправления `hotfix/x.y.z-` от этого тега. -3. Исправьте проблему и проведите обязательные проверки. -4. Включите исправление через одобренный PR в релизную ветку `release/x.y`. -5. Подготовьте файлы патч-релиза `vX.Y.(Z+1)` в ветке `task/` от этой релизной ветки и включите их туда через одобренный PR. После обязательных проверок, включая `make tests-e2e`, зафиксируйте коммит слияния и [опубликуйте тег](#3-создание-и-публикация-тега). -6. Верните изменения срочного исправления в ветку `master` отдельным PR из рабочей ветки. +1. Определите текущий тег рабочей среды `vX.Y.Z` и создайте от него `hotfix/x.y.z-`. +2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в этой же ветке. +3. Выполните обязательные проверки, включая `make check` по правилам проекта и `make tests-e2e`. Откройте PR из `hotfix/*` в основную ветку, получите одобрение проверенного состояния и разрешение на выпуск. +4. Зафиксируйте SHA одобренного коммита `hotfix/*` и [опубликуйте тег](#3-создание-и-публикация-тега) на нём. Не используйте для срочного выпуска коммит основной ветки с другими изменениями. +5. Сразу после выпуска включите этот PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если для слияния нужны доработки, повторите проверки и одобрение; тег уже выпущенного исправления остаётся неизменным. -Если релизная ветка рабочей версии закрыта, до открытия PR согласуйте целевую ветку патч-релиза с пользователем. Не подставляйте ветку следующей версии; закрытие другой активной линии этот сценарий не предписывает. Верните исправление в `master` отдельным PR сразу после выпуска. +Входящий PR в `release/*` и отдельная ветка подготовки файлов не нужны. Другая активная релизная ветка сохраняется; при её дальнейшей синхронизации с основной веткой исправление войдёт в следующий обычный релиз. ## Recovery Policy diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 1c0d542..0662762 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -13,7 +13,8 @@ package: prikotov/git-workflow ## Правила -- Релизные документы `docs/releases/vX.Y.Z/` готовятся в ветке `task/` от актуальной `master`/`main` и включаются туда через одобренный запрос на слияние (Pull Request, PR) до создания релизной ветки и тега: [процесс релиза](../release.md#выпуск-релиза). +- Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач, в том числе задолго до выпуска. В них фиксируются необходимые действия до и после релиза. +- При финализации в `release/x.y` проверяются полнота, актуальность и соответствие документов составу релиза. Итог включается через запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку до публикации тега: [процесс релиза](../release.md#выпуск-релиза). - Для срочного исправления от рабочего тега используется [отдельный порядок подготовки](../release.md#hotfix-и-patch-release). - Минимально обязательный файл в каталоге релиза: `release-plan.md`. - Файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 62818ee..a2f3b9b 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,6 +1,6 @@ # План релиза vX.Y.Z -Заполните план до одобрения PR (запроса на слияние) подготовки релиза. Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. +Дополняйте план по мере выполнения задач. При финализации релиза проверьте его полноту и актуальность до одобрения PR (запроса на слияние). Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. ## Метаданные @@ -10,8 +10,9 @@ - Линия релиза: `release/x.y` - Сценарий: обычный релиз из основной ветки / срочное исправление от рабочего тега (указать одно) - Основная ветка: `master` / `main` -- База рабочей ветки и цель PR: для обычного релиза — основная ветка; для срочного исправления — согласованная ветка патч-релиза -- Рабочая ветка подготовки: `task/` +- База: актуальная основная ветка / рабочий тег для срочного исправления +- Рабочая ветка финализации: `release/x.y` / `hotfix/x.y.z-` +- Цель PR: основная ветка - PR подготовки релиза: - Ответственный: - Плановая дата deploy: @@ -38,8 +39,8 @@ ## План проверок перед выкладкой - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов -- Убедиться, что этот план, остальные релизные файлы и исправления обычного релиза включены через одобренные PR в основную ветку до создания релизной ветки и тега -- Для обычного релиза проверить, что релизная ветка и тег указывают на согласованный актуальный коммит основной ветки +- Для обычного релиза проверить, что PR из `release/x.y` с итоговыми документами и исправлениями включён в основную ветку до публикации тега +- Проверить, что тег обычного релиза отмечает результат этого PR, содержимое которого совпадает с одобренным состоянием релизной ветки - Для срочного исправления проверить состав и коммит по отдельному сценарию в Git-регламенте проекта, а также план возврата исправления в основную ветку - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 5184beb..5f28a49 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 15:58:21 (1789142301) +completed: 2026-09-11 23:31:49 (1789169509) cancelled: value: V2 complexity: C2 @@ -48,8 +48,9 @@ status: done ## 3. Требования, MoSCoW (Requirements) ### 🔴 Обязательно (Must Have) -- [x] По уточнению пользователя обычный релиз готовить в рабочей ветке от актуальной основной ветки `master`/`main`, направлять PR туда же и включать код и релизные файлы до выпуска. Подготовку срочного исправления от рабочего тега описывать отдельно. -- [x] Сохранить запрет прямых коммитов в `master` и `release/*`; подготовку релизных файлов выполнять в рабочей ветке через PR. +- [x] Финализировать обычный релиз в `release/x.y` от актуальной основной ветки `master`/`main`; PR направлять из неё в основную ветку до выпуска. Срочное исправление от рабочего тега описывать отдельно. +- [x] Включать изменения в основную ветку только через PR; разрешить работу и коммиты в `release/*`, исключить входящие PR в неё и промежуточную ветку `task/prepare-release-*`. +- [x] Разрешить создавать и дополнять релизные документы заранее в рамках обычных задач; при финализации проверять накопленное, не заменять существующий план шаблоном. - [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. - [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. - [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. @@ -81,7 +82,7 @@ git diff --check ### Результат выполнения - Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. -- Релизные файлы обычного релиза готовятся в рабочей ветке `task/` от актуального `master`/`main` и включаются туда через одобренный PR. Релизная ветка и неизменяемый тег фиксируют выбранный актуальный коммит основной ветки. Автокоммит, автотег и публикация всех тегов исключены; срочное исправление от рабочего тега описано отдельно. +- Документы релиза накапливаются в обычных задачах. Финализация выполняется в `release/x.y` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены; срочное исправление от рабочего тега описано отдельно. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Параметры `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`. @@ -103,15 +104,26 @@ git diff --check - Повторно выполнены `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` и трёх способов слияния: создание рабочей релизной ветки с ранними документами, коммиты финализации, отказ до включения в основную ветку, проверка результата слияния и более поздних изменений, публикация только выбранного неизменяемого тега. Реальные репозитории при этих испытаниях не сливались и не тегировались. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. @@ -134,3 +146,4 @@ git diff --check | 2026-09-11 | Технический писатель (pi) | Повторная личная вычитка по замечаниям пользователя: исправлены терминология, проверки релиза, сценарий срочного исправления и шаблон плана; проверки повторены | | 2026-09-11 | Технический писатель (pi) | По уточнению пользователя обычный релиз переведён на источник master/main: подготовка через PR в основную ветку, фиксация её коммита, отдельный сценарий срочного исправления | | 2026-09-11 | Технический писатель (pi) | По запросу пользователя убраны пояснение «имя ветки, а не путь», повторы и многословные оговорки в инструкциях, чеклистах и шаблоне; правила сохранены | +| 2026-09-11 | Технический писатель (pi) | Исправлена ошибочная модель агента: финализация и коммиты в release/*, PR из неё в master/main; документы накапливаются заранее в обычных задачах | From 9e07dd34aa37a696122d669ef67ba29932bd5075 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 06:43:49 +0700 Subject: [PATCH 07/40] =?UTF-8?q?docs(workflow):=20remove=20redundant=20wo?= =?UTF-8?q?rding=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=B8=D0=B7?= =?UTF-8?q?=D0=B1=D1=8B=D1=82=D0=BE=D1=87=D0=BD=D1=8B=D0=B5=20=D1=84=D0=BE?= =?UTF-8?q?=D1=80=D0=BC=D1=83=D0=BB=D0=B8=D1=80=D0=BE=D0=B2=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 4 ++-- docs/git-workflow/commits.md | 2 +- docs/git-workflow/pull-request.md | 12 +++++------ docs/git-workflow/release-checklists.md | 2 +- docs/git-workflow/release.md | 21 +++++++++---------- docs/git-workflow/releases/index.md | 5 ++--- .../templates/release-plan.template.md | 2 +- ...K-docs-align-workflow-instructions.todo.md | 3 ++- 8 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index a55dff4..993cddb 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -57,7 +57,7 @@ git switch -c task/ ### Release branch -Создаётся от актуальной основной ветки при начале финализации выпуска: [процесс релиза](release.md#1-финализация-в-релизной-ветке). +Создаётся от актуальной основной ветки для финализации релиза: [процесс релиза](release.md#1-финализация-в-релизной-ветке). Правила для `release/x.y`: - необходимые исправления, версии и итоговые релизные документы коммитятся в этой ветке; @@ -101,7 +101,7 @@ git merge "origin/$base" git rebase "origin/$base" ``` -Синхронизацию заверши до окончательного одобрения PR. Если после одобрения нужны изменения — повтори проверки и запроси новое одобрение по [правилам PR](pull-request.md#подготовка-pr). +Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). ## Завершение diff --git a/docs/git-workflow/commits.md b/docs/git-workflow/commits.md index abe6da4..d15ab9f 100644 --- a/docs/git-workflow/commits.md +++ b/docs/git-workflow/commits.md @@ -160,7 +160,7 @@ vendor/bin/validate-commit .git/COMMIT_EDITMSG - Обход хуков через `--no-verify` запрещён без явного исключения в политике проекта-потребителя. - Исключение должно определять условия обхода и необходимые замещающие проверки; укажи основание и результаты в PR. -- Срочность сама по себе не разрешает обход. Формат сообщения сохраняется при любом исключении. +- Формат сообщения сохраняется при любом исключении. ### CI diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 1d5e5c7..b63cd5a 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -48,7 +48,7 @@ package: prikotov/git-workflow - По умолчанию перед PR обязателен успешный `make check`, в том числе для `docs-only` и служебных изменений. - Пропуск или замена проверки допустимы только по явной политике проекта-потребителя (например, в его `AGENTS.md`): должны быть указаны применимые категории изменений и необходимые проверки вместо пропущенной. -- При отсутствии такого исключения проверки обязательны. Отсутствующая команда или сбой окружения не считаются успешной проверкой и не разрешают пропуск. +- Отсутствие команды или сбой окружения не разрешают пропуск проверки. - В PR укажи выполненные команды, результаты и ссылку на применимое проектное исключение, если оно использовано. - Исключение для `make check` не отменяет остальные обязательные проверки и CI, если политика явно не определяет иное. @@ -61,7 +61,7 @@ package: prikotov/git-workflow - Создай PR с [выбранной базой](#выбор-base-branch): `gh pr create --base --head "$(git branch --show-current)"`. - Тело PR передавай через `gh pr create --body-file`. - Предпочитай `--body-file -` (stdin) или файл в `tmp/`. -- Связь задачи с PR и переходы статусов веди по установленным в проекте правилам `todo-md`. Формат полей и механика задач не определяются этим пакетом. +- Связь задачи с PR и переходы статусов веди по правилам `todo-md` проекта. ## Оформление PR @@ -98,11 +98,11 @@ package: prikotov/git-workflow - Заверши все изменения в PR-ветке до запроса окончательного одобрения (approve), включая релизные файлы и служебные обновления задачи по правилам `todo-md` проекта. - Если PR завершает реализацию задачи, оформи `done` по правилам `todo-md` проекта и опубликуй изменения до окончательного одобрения. -- PR только с постановкой не завершает реализацию поставленной задачи: она остаётся в `todo` или `backlog` по правилам проекта. Если работа над постановкой ведётся отдельной задачей, заверши только её. +- В PR постановки будущая задача остаётся в `todo` или `backlog`. Если постановка оформлена отдельной задачей, заверши только её. - После последнего push дождись зелёного CI и выполни обязательные проверки окончательного состояния PR. -- Запроси одобрение пользователя именно на это состояние PR. -- После одобрения не добавляй коммиты и не пушь в PR-ветку — в том числе ради статуса задачи, ссылки на PR или отчёта. Это относится и к служебным рабочим PR. -- Если правки или синхронизация всё же необходимы, прежнего одобрения недостаточно: внеси изменения, повтори проверки и получи новое окончательное одобрение до merge. +- Запроси одобрение проверенного состояния PR. +- После одобрения не меняй PR-ветку, включая служебные данные. +- Доработки и синхронизация требуют повторных проверок и нового одобрения до merge. ## Перед merge diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 95e4f7c..7bfd6d3 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -8,7 +8,7 @@ package: prikotov/git-workflow ## Чеклист подготовки релиза -Этот чеклист относится к обычному релизу, включая обычное повышение `patch`. Срочное исправление от рабочего тега описано отдельно ниже. Основная ветка проекта — `master` или `main`. +Для обычного релиза, включая `patch`, из основной ветки `master`/`main`. - Согласован состав релиза из актуальной основной ветки. - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index b45811c..1af7ae9 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,11 +4,10 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Обычный релиз выпускается из актуальной основной ветки проекта — `master` или `main`. Ниже в примерах используется `master`; если основная ветка называется `main`, замените имя в командах. Выкладка в рабочую среду (production) выполняется по неизменяемому тегу `vX.Y.Z`. +Обычный релиз выпускается из актуальной основной ветки проекта — `master` или `main`. В примерах используется `master`; для `main` замените имя в командах. Выкладка в рабочую среду (production) выполняется по неизменяемому тегу `vX.Y.Z`. ## Модель релизов -- Документы будущего релиза можно создавать и дополнять в рамках обычных задач, до создания релизной ветки. - Для финализации обычного релиза создаётся рабочая ветка `release/x.y` от актуальной основной ветки. - Исправления и релизные файлы коммитятся в `release/x.y`. Из неё открывается запрос на слияние (Pull Request, PR) в основную ветку; входящие PR в `release/*` не используются. - После проверок и одобрения PR включается в основную ветку до публикации тега. Тег отмечает проверенный результат этого слияния. @@ -34,13 +33,13 @@ 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`. Выбранную версию явно передавайте генератору; его автоматическое повышение не заменяет эти правила, особенно для `0.x`. +Тип релиза определяется по истории Conventional Commits: `fix` требует `patch`, `feat` — `minor`, а `BREAKING CHANGE` или `!` — `minor` при текущей версии `0.x` и `major` начиная с `1.0.0`. Выбранную по этим правилам версию явно передавайте генератору. Обычный патч-релиз также выпускается из актуальной основной ветки. `patch` сохраняет номер линии `x.y`, а `minor` и `major` меняют его. ## Подготовка коммитов -Сообщения готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. Это относится и к релизным коммитам: генератор сообщений не используется. +Сообщения всех коммитов, включая релизные, готовьте вручную по [правилам коммитов](commits.md): Conventional Commits, английский и русский текст через косую черту. ```bash git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" @@ -60,7 +59,7 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## План релиза -Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач. В них заранее записываются необходимые действия до и после выпуска. +Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач. В них фиксируются необходимые действия до и после релиза. При финализации в `release/x.y` проверьте полноту, актуальность и соответствие документов составу релиза. Если `release-plan.md` ещё нет, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не заменяйте шаблоном. До одобрения PR план должен быть заполнен. Без него выкладка запрещена. @@ -75,7 +74,7 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## Работа с CHANGELOG -Генерируйте файлы в `release/*`, для срочного исправления — в `hotfix/*`. Если проект использует `marcocesarato/php-conventional-changelog`, документированный вызов без автоматического коммита и тега: +Генерируйте файлы в `release/*`, для срочного исправления — в `hotfix/*`. Если проект использует `marcocesarato/php-conventional-changelog`, запускайте его без автоматического коммита и тега: ```bash php vendor/bin/conventional-changelog --ver="X.Y.Z" --no-tag --merged @@ -84,9 +83,9 @@ git diff - Замените `X.Y.Z` выбранной версией без префикса `v`; `--merged` ограничивает историю коммитами, достижимыми из `HEAD`. - Не используйте `--commit`, `--commit-all` или `--amend`. Проверьте конфигурацию `.changelog` и её callbacks: они тоже не должны создавать коммиты, теги или выполнять публикацию. -- Команда записывает файлы, это не dry run. Проверьте весь diff: кроме `CHANGELOG.md` могут измениться файлы версий (`composer.json`, `package.json` и другие по конфигурации). +- Команда изменяет файлы. Проверьте весь diff, включая `CHANGELOG.md` и файлы версий. - Если генератор не установлен, подготовьте файлы вручную по тем же правилам. Этот пакет не поставляет генератор или цели `make release-*`. -- Не запускайте обёртки `make release`, `make release-*` или `make changelog`, пока не проверены их действия. Автоматический релизный коммит/тег не входит в этот процесс. +- Не запускайте обёртки `make release`, `make release-*` или `make changelog`, пока не проверены их действия. `CHANGELOG.md` должен оставаться коротким: - заголовок релиза; @@ -143,7 +142,7 @@ 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 ``` -- Публикуется только конкретный тег, не все локальные теги; `git push --tags` запрещён. +- Публикуйте только выбранный тег; `git push --tags` запрещён. - Тег production неизменяем: не перемещайте, не перезаписывайте и не публикуйте его с `--force`. - На защищённой ветке не создаётся дополнительный релизный коммит; генератор после merge не запускается. @@ -155,7 +154,7 @@ git tag -a vX.Y.Z "$release_commit" -m "Release vX.Y.Z" && gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ``` -Или используйте `--generate-notes` вместо `--notes-file`. Подробные notes подготовьте до публикации; `--verify-tag` не позволяет неявно создать отсутствующий тег. Деплой выполняется только по этому фиксированному тегу. +Или используйте `--generate-notes` вместо `--notes-file`. Описание подготовьте до публикации; `--verify-tag` запрещает неявное создание тега. ## Hotfix и patch release @@ -167,7 +166,7 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md 4. Зафиксируйте SHA одобренного коммита `hotfix/*` и [опубликуйте тег](#3-создание-и-публикация-тега) на нём. Не используйте для срочного выпуска коммит основной ветки с другими изменениями. 5. Сразу после выпуска включите этот PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если для слияния нужны доработки, повторите проверки и одобрение; тег уже выпущенного исправления остаётся неизменным. -Входящий PR в `release/*` и отдельная ветка подготовки файлов не нужны. Другая активная релизная ветка сохраняется; при её дальнейшей синхронизации с основной веткой исправление войдёт в следующий обычный релиз. +Активная релизная ветка сохраняется; исправление попадёт в неё при синхронизации с основной веткой. ## Recovery Policy diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 0662762..b778aea 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -13,11 +13,10 @@ package: prikotov/git-workflow ## Правила -- Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач, в том числе задолго до выпуска. В них фиксируются необходимые действия до и после релиза. +- Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач. В них фиксируются необходимые действия до и после релиза. - При финализации в `release/x.y` проверяются полнота, актуальность и соответствие документов составу релиза. Итог включается через запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку до публикации тега: [процесс релиза](../release.md#выпуск-релиза). - Для срочного исправления от рабочего тега используется [отдельный порядок подготовки](../release.md#hotfix-и-patch-release). -- Минимально обязательный файл в каталоге релиза: `release-plan.md`. -- Файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. +- Обязательный файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. - Результаты проверок и выкладки записываются в комментариях к PR подготовки релиза. - Для срочного исправления (hotfix) и патч-релиза (patch release) создаётся отдельный каталог с номером новой версии. diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index a2f3b9b..08d5bf3 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,6 +1,6 @@ # План релиза vX.Y.Z -Дополняйте план по мере выполнения задач. При финализации релиза проверьте его полноту и актуальность до одобрения PR (запроса на слияние). Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) проверьте полноту и актуальность плана. Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. ## Метаданные diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 5f28a49..d0715e4 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 23:31:49 (1789169509) +completed: 2026-09-11 23:42:58 (1789170178) cancelled: value: V2 complexity: C2 @@ -147,3 +147,4 @@ git diff --check | 2026-09-11 | Технический писатель (pi) | По уточнению пользователя обычный релиз переведён на источник master/main: подготовка через PR в основную ветку, фиксация её коммита, отдельный сценарий срочного исправления | | 2026-09-11 | Технический писатель (pi) | По запросу пользователя убраны пояснение «имя ветки, а не путь», повторы и многословные оговорки в инструкциях, чеклистах и шаблоне; правила сохранены | | 2026-09-11 | Технический писатель (pi) | Исправлена ошибочная модель агента: финализация и коммиты в release/*, PR из неё в master/main; документы накапливаются заранее в обычных задачах | +| 2026-09-11 | Технический писатель (pi) | Убраны «задолго до выпуска», повторы и избыточные пояснения; правила и команды сохранены | From 9855878043d4d21bd88cf6e4b03bb1672209f0cb Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 06:57:05 +0700 Subject: [PATCH 08/40] =?UTF-8?q?docs(workflow):=20express=20rules=20as=20?= =?UTF-8?q?actions=20/=20=D0=B7=D0=B0=D0=BF=D0=B8=D1=81=D0=B0=D1=82=D1=8C?= =?UTF-8?q?=20=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=B0=20=D0=BA=D0=B0?= =?UTF-8?q?=D0=BA=20=D0=B4=D0=B5=D0=B9=D1=81=D1=82=D0=B2=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 26 ++++++------ docs/git-workflow/deploy.md | 9 ++--- docs/git-workflow/pull-request.md | 12 +++--- docs/git-workflow/release-checklists.md | 10 ++--- docs/git-workflow/release.md | 40 +++++++++---------- docs/git-workflow/releases/index.md | 13 +++--- .../templates/release-plan.template.md | 4 +- ...K-docs-align-workflow-instructions.todo.md | 3 +- 8 files changed, 56 insertions(+), 61 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 993cddb..04acefe 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -17,15 +17,15 @@ package: prikotov/git-workflow - `master` или `main` — основная ветка разработки и источник обычных релизов. В примерах ниже используется `master`; для проекта с `main` замените имя в командах. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. -- `release/x.y` — рабочая ветка финализации релиза от актуальной основной ветки; результат включается в основную ветку через PR. +- `release/x.y` — рабочая ветка финализации релиза от актуальной основной ветки. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки. - Одновременно поддерживается только одна активная `release/x.y`. ## Общие правила -- Изменения в `master`/`main` включаются только через PR. -- В `task/*`, `release/*` и `hotfix/*` работают и коммитят по запросу пользователя. Входящие PR в `release/*` не используются. +- Вноси изменения в `master`/`main` только через PR. +- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. Не направляй PR в `release/*`. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. @@ -57,13 +57,13 @@ git switch -c task/ ### Release branch -Создаётся от актуальной основной ветки для финализации релиза: [процесс релиза](release.md#1-финализация-в-релизной-ветке). +Создай от актуальной основной ветки для финализации релиза: [процесс релиза](release.md#1-финализация-в-релизной-ветке). Правила для `release/x.y`: -- необходимые исправления, версии и итоговые релизные документы коммитятся в этой ветке; -- PR направляется из `release/x.y` в основную ветку и включается до публикации тега; -- обычные задачи продолжают идти в основную ветку; перед окончательным одобрением релизная ветка синхронизируется с ней; -- для уже начатого выпуска используется существующая ветка; перед новым выпуском предыдущая линия завершается, принудительная перезапись запрещена. +- коммить исправления, версии и релизные документы в этой ветке; +- направляй PR из неё в основную ветку; слей PR до публикации тега; +- PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y`; +- продолжай начатый выпуск в существующей ветке; перед новым выпуском закрой предыдущую линию, не перезаписывай ветку принудительно. ### Hotfix branch @@ -74,11 +74,11 @@ git fetch origin --tags --prune git switch -c hotfix/x.y.z- vX.Y.Z ``` -Исправление и файлы патч-релиза готовятся в этой же ветке. Тег ставится на её одобренный коммит, изменения включаются в основную ветку через PR: [сценарий срочного исправления](release.md#hotfix-и-patch-release). +Подготовь исправление и файлы патч-релиза в этой ветке. Выпусти патч и слей PR в основную ветку по [сценарию срочного исправления](release.md#hotfix-и-patch-release). ## Синхронизация -- `task/*` и `release/*` синхронизируются с основной веткой `master`/`main` до окончательного одобрения PR. +- Синхронизируй `task/*` и `release/*` с основной веткой `master`/`main` до окончательного одобрения PR. - До выпуска `hotfix/*` не подтягивай в неё ещё не выпущенные изменения основной ветки. После выпуска подготовь возврат исправления через PR в основную ветку. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. @@ -105,6 +105,6 @@ git rebase "origin/$base" ## Завершение -- `task/*` удаляется локально и в `origin` после слияния PR. -- `release/*` сохраняется до завершения выпуска и закрытия линии; её изменения должны быть включены в основную ветку. Для выпущенной версии остаётся неизменяемый тег; отменённый кандидат не тегируется. -- `hotfix/*` удаляется после выпуска и включения исправления в основную ветку. +- Удали `task/*` локально и в `origin` после слияния PR. +- Сохраняй `release/*` до завершения выпуска и закрытия линии. Перед удалением проверь, что изменения слиты в основную ветку. Сохрани тег выпущенной версии; отменённого кандидата не тегируй. +- Удали `hotfix/*` после выпуска и слияния исправления в основную ветку. diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 055388f..d344602 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,8 +28,7 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Финализировать обычный релиз в `release/x.y` от актуальной `master`/`main`: актуализировать документы, подготовить версии и необходимые исправления. -2. Выполнить обязательные проверки, включая `make tests-e2e`, и включить одобренный PR (запрос на слияние) из `release/x.y` в основную ветку. Проверить результат слияния и опубликовать тег по [процессу релиза](release.md#выпуск-релиза). Срочное исправление от рабочего тега готовится по [отдельному сценарию](release.md#hotfix-и-patch-release). -3. Выполнить deploy exact `vX.Y.Z` по актуальному runbook. -4. Провести post-check: основные user-flow, логи, метрики. -5. При проблеме остановить rollout и выпустить hotfix или patch release. +1. Подготовить выпуск по [процессу релиза](release.md#выпуск-релиза) или [сценарию срочного исправления](release.md#hotfix-и-patch-release), пройти обязательные проверки, включая `make tests-e2e`, и опубликовать тег. +2. Развернуть выбранный тег `vX.Y.Z` по инструкции выкладки проекта (runbook). +3. Проверить основные пользовательские сценарии, логи и метрики. +4. При проблеме остановить выкладку и выпустить срочное исправление (hotfix) или патч-релиз (patch release). diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index b63cd5a..9cb6dae 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -16,7 +16,7 @@ package: prikotov/git-workflow ## Правила -- Изменения в `master`/`main` включаются только через PR. В рабочих ветках `task/*`, `release/*` и `hotfix/*` коммиты разрешены по запросу пользователя. +- Вноси изменения в `master`/`main` только через PR. Коммить в рабочих ветках `task/*`, `release/*` и `hotfix/*` только по запросу пользователя. - Одна задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. @@ -40,8 +40,8 @@ package: prikotov/git-workflow - Цель PR — основная ветка `master` или `main`. Далее она обозначается как `master`. - Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. -- Финализация релиза: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. Входящие PR в `release/*` не используются. -- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку. Выпуск и возврат изменений выполняются по [отдельному сценарию](release.md#hotfix-и-patch-release). +- Финализация релиза: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. Не направляй PR в `release/*`. +- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку. Следуй [сценарию срочного исправления](release.md#hotfix-и-patch-release). - До выпуска срочного исправления не синхронизируй его ветку с основной. Если для слияния нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. ## Обязательные проверки @@ -98,11 +98,11 @@ package: prikotov/git-workflow - Заверши все изменения в PR-ветке до запроса окончательного одобрения (approve), включая релизные файлы и служебные обновления задачи по правилам `todo-md` проекта. - Если PR завершает реализацию задачи, оформи `done` по правилам `todo-md` проекта и опубликуй изменения до окончательного одобрения. -- В PR постановки будущая задача остаётся в `todo` или `backlog`. Если постановка оформлена отдельной задачей, заверши только её. +- В PR постановки оставь будущую задачу в `todo` или `backlog`. Если постановка оформлена отдельной задачей, заверши только её. - После последнего push дождись зелёного CI и выполни обязательные проверки окончательного состояния PR. - Запроси одобрение проверенного состояния PR. - После одобрения не меняй PR-ветку, включая служебные данные. -- Доработки и синхронизация требуют повторных проверок и нового одобрения до merge. +- После доработок или синхронизации повтори проверки и запроси новое одобрение до merge. ## Перед merge @@ -113,7 +113,7 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- PR обычного релиза из `release/*` включается в основную ветку до публикации тега; PR срочного исправления — сразу после его выпуска. +- Слей PR обычного релиза до публикации тега, PR срочного исправления — сразу после выпуска. ## После merge diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 7bfd6d3..0bebc02 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -15,13 +15,13 @@ package: prikotov/git-workflow - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. - Рабочая ветка `release/x.y` создана от актуальной основной ветки по [процессу релиза](release.md#1-финализация-в-релизной-ветке). -- Накопленные в задачах документы проверены и актуализированы; существующий `release-plan.md` сохранён, действия до и после выпуска учтены. +- Документы обновлены под состав релиза и содержат действия до и после выпуска. Существующий `release-plan.md` не перезаписан шаблоном. - Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y` вручную, без автоматического тега. - PR (запрос на слияние) открыт из `release/x.y` в основную ветку; синхронизация завершена до окончательного одобрения. -- Все правки, включая служебные обновления задачи, включены до окончательных проверок и одобрения PR. +- Все изменения, включая данные задачи, закоммичены до окончательных проверок и одобрения PR. - Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. -- Окончательное состояние PR одобрено пользователем, автоматические проверки PR (CI) успешны, слияние в основную ветку подтверждено и выполнено через GitHub. -- Зафиксированы SHA одобренной релизной ветки и результата слияния PR. Проверены принадлежность результата основной ветке и совпадение содержимого: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). +- Автоматические проверки PR (CI) успешны. Пользователь одобрил проверенный PR и подтвердил слияние; PR слит через GitHub. +- Коммит слияния входит в историю основной ветки и совпадает по содержимому с одобренным коммитом `release/x.y`; оба SHA зафиксированы: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). ## Чеклист срочного исправления @@ -29,7 +29,7 @@ package: prikotov/git-workflow - Определён текущий тег релиза на production `vX.Y.Z`. - Рабочая ветка срочного исправления `hotfix/x.y.z-` создана от тега рабочей среды, а не от ветки `master`. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; PR направлен в основную ветку, включение запланировано сразу после выпуска. +- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; PR направлен в основную ветку, слияние запланировано сразу после выпуска. - Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки успешны. - Проверенное состояние одобрено, выпуск разрешён. Тег отмечает зафиксированный коммит `hotfix/*` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 1af7ae9..ce35e93 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,17 +4,17 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Обычный релиз выпускается из актуальной основной ветки проекта — `master` или `main`. В примерах используется `master`; для `main` замените имя в командах. Выкладка в рабочую среду (production) выполняется по неизменяемому тегу `vX.Y.Z`. +Основная ветка проекта — `master` или `main`. В примерах используется `master`; для `main` замените имя в командах. ## Модель релизов -- Для финализации обычного релиза создаётся рабочая ветка `release/x.y` от актуальной основной ветки. -- Исправления и релизные файлы коммитятся в `release/x.y`. Из неё открывается запрос на слияние (Pull Request, PR) в основную ветку; входящие PR в `release/*` не используются. -- После проверок и одобрения PR включается в основную ветку до публикации тега. Тег отмечает проверенный результат этого слияния. -- Изменения в `master`/`main` включаются только через PR. Коммиты в рабочих ветках `task/*`, `release/*` и `hotfix/*` разрешены по запросу пользователя. -- Рабочая среда всегда разворачивается по **конкретному тегу**, а не по последнему коммиту ветки. -- Одновременно поддерживается только одна активная релизная ветка `release/x.y`. -- Срочное исправление от рабочего тега — исключение: [Hotfix и patch release](#hotfix-и-patch-release). +- Финализируйте обычный релиз в `release/x.y` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. +- Направляйте запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку. +- После проверок и одобрения слейте PR. Поставьте тег на проверенный коммит слияния. +- Изменяйте `master`/`main` только через PR. Коммитьте в рабочих ветках только по запросу пользователя. +- Разворачивайте рабочую среду (production) по неизменяемому тегу `vX.Y.Z`, не по последнему коммиту ветки. +- Поддерживайте только одну активную `release/x.y`. +- Для срочного исправления от рабочего тега следуйте [отдельному сценарию](#hotfix-и-patch-release). ## SemVer и линии релиза @@ -53,15 +53,13 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" ## Release cut -Финализация выпуска начинается с создания `release/x.y` от актуальной основной ветки. В ней уточняются состав релиза, документы и необходимые исправления. - -До окончательного одобрения синхронизируйте релизную ветку с основной и проверьте весь получившийся состав. После одобрения состав не меняется без повторных проверок и нового одобрения: [правила PR](pull-request.md#подготовка-pr). Окончательный коммит выпуска фиксируется после слияния PR в основную ветку. +Зафиксируйте состав релиза при окончательном одобрении PR. При изменении состава повторите проверки и запросите новое одобрение по [правилам PR](pull-request.md#подготовка-pr). ## План релиза -Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач. В них фиксируются необходимые действия до и после релиза. +Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. -При финализации в `release/x.y` проверьте полноту, актуальность и соответствие документов составу релиза. Если `release-plan.md` ещё нет, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не заменяйте шаблоном. До одобрения PR план должен быть заполнен. Без него выкладка запрещена. +При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. В `release-plan.md` обязательно зафиксируйте: - состав релиза и его границы; @@ -110,7 +108,7 @@ git switch master && git push -u origin release/x.y ``` -1. В `release/x.y` подготовьте `CHANGELOG.md`, файлы версий, актуализируйте накопленные документы и внесите необходимые исправления. +1. В `release/x.y` внесите исправления, обновите `CHANGELOG.md`, файлы версий и релизные документы. 2. Проверьте diff и создайте коммиты вручную по [commits.md](commits.md). 3. Откройте PR **из `release/x.y` в основную ветку** по [правилам PR](pull-request.md). 4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните `make check` и обязательный предрелизный запуск `make tests-e2e`; дождитесь успеха. Проектные исключения для `make check` не отменяют сквозные тесты. @@ -118,9 +116,9 @@ git switch master && ### 2. Проверка коммита выпуска -После слияния возьмите SHA результата PR в основной ветке и сравните его содержимое с одобренным состоянием `release/x.y`. Более поздние коммиты основной ветки не подменяют этот результат. +Получите SHA коммита слияния PR из GitHub. Сравните его содержимое с одобренным коммитом `release/x.y`. Не подставляйте текущий `HEAD` основной ветки. -Подставьте полные SHA результата слияния и одобренной релизной ветки: +Подставьте полные SHA коммита слияния и одобренного коммита релизной ветки: ```bash release_commit=VERIFIED_MERGE_SHA @@ -130,7 +128,7 @@ git fetch origin && git diff --exit-code "$release_head" "$release_commit" -- ``` -При ошибке или различиях выпуск останавливается. Согласуйте изменившийся состав, проверьте новые изменения кода, зависимостей и конфигурации; необходимые доработки включите новым PR из релизной ветки в основную. Новый SHA при неизменном содержимом сам по себе не требует полного повторного прогона или отдельного CI. +При ошибке или различиях остановите выпуск. Согласуйте состав и проверьте изменения кода, зависимостей и конфигурации. Доработки слейте новым PR из релизной ветки в основную. Если изменился только SHA, а содержимое совпадает, повторный полный прогон и отдельный CI не требуются. ### 3. Создание и публикация тега @@ -144,7 +142,7 @@ git tag -a vX.Y.Z "$release_commit" -m "Release vX.Y.Z" && - Публикуйте только выбранный тег; `git push --tags` запрещён. - Тег production неизменяем: не перемещайте, не перезаписывайте и не публикуйте его с `--force`. -- На защищённой ветке не создаётся дополнительный релизный коммит; генератор после merge не запускается. +- После слияния не запускайте генератор и не создавайте релизный коммит в основной ветке. ### 4. GitHub Release @@ -158,15 +156,15 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Hotfix и patch release -Срочное исправление готовится от рабочего тега, без ещё не выпущенных изменений основной ветки: +Не добавляйте в срочное исправление невыпущенные изменения основной ветки. 1. Определите текущий тег рабочей среды `vX.Y.Z` и создайте от него `hotfix/x.y.z-`. 2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в этой же ветке. 3. Выполните обязательные проверки, включая `make check` по правилам проекта и `make tests-e2e`. Откройте PR из `hotfix/*` в основную ветку, получите одобрение проверенного состояния и разрешение на выпуск. 4. Зафиксируйте SHA одобренного коммита `hotfix/*` и [опубликуйте тег](#3-создание-и-публикация-тега) на нём. Не используйте для срочного выпуска коммит основной ветки с другими изменениями. -5. Сразу после выпуска включите этот PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если для слияния нужны доработки, повторите проверки и одобрение; тег уже выпущенного исправления остаётся неизменным. +5. Сразу после выпуска слейте PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если нужны доработки, повторите проверки и запросите новое одобрение. Не меняйте опубликованный тег. -Активная релизная ветка сохраняется; исправление попадёт в неё при синхронизации с основной веткой. +Не закрывайте активную релизную ветку ради срочного исправления; перенесите исправление при следующей синхронизации с основной веткой. ## Recovery Policy diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index b778aea..d3cdaa2 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -4,8 +4,6 @@ package: prikotov/git-workflow # Артефакты релиза -Этот раздел описывает документы, которые создаются для конкретного релиза в рабочую среду (production). - ## Структура - `docs/git-workflow/templates/release-plan.template.md` — шаблон плана релиза. @@ -13,12 +11,11 @@ package: prikotov/git-workflow ## Правила -- Документы в `docs/releases/vX.Y.Z/` создаются и дополняются по мере выполнения задач. В них фиксируются необходимые действия до и после релиза. -- При финализации в `release/x.y` проверяются полнота, актуальность и соответствие документов составу релиза. Итог включается через запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку до публикации тега: [процесс релиза](../release.md#выпуск-релиза). -- Для срочного исправления от рабочего тега используется [отдельный порядок подготовки](../release.md#hotfix-и-patch-release). -- Обязательный файл `release-plan.md` фиксирует состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. -- Результаты проверок и выкладки записываются в комментариях к PR подготовки релиза. -- Для срочного исправления (hotfix) и патч-релиза (patch release) создаётся отдельный каталог с номером новой версии. +- Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. +- При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. +- Заполните обязательный `release-plan.md`: состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. +- Результаты проверок и выкладки записывайте в комментариях к запросу на слияние (Pull Request, PR) подготовки релиза. +- Для срочного исправления (hotfix) и патч-релиза (patch release) создавайте отдельный каталог с номером новой версии. ## Шаблон diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 08d5bf3..86faaee 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -39,8 +39,8 @@ ## План проверок перед выкладкой - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов -- Для обычного релиза проверить, что PR из `release/x.y` с итоговыми документами и исправлениями включён в основную ветку до публикации тега -- Проверить, что тег обычного релиза отмечает результат этого PR, содержимое которого совпадает с одобренным состоянием релизной ветки +- До публикации тега обычного релиза проверить, что PR из `release/x.y` слит в основную ветку +- Проверить, что тег обычного релиза указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` - Для срочного исправления проверить состав и коммит по отдельному сценарию в Git-регламенте проекта, а также план возврата исправления в основную ветку - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index d0715e4..e63ac0f 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 23:42:58 (1789170178) +completed: 2026-09-11 23:56:06 (1789170966) cancelled: value: V2 complexity: C2 @@ -148,3 +148,4 @@ git diff --check | 2026-09-11 | Технический писатель (pi) | По запросу пользователя убраны пояснение «имя ветки, а не путь», повторы и многословные оговорки в инструкциях, чеклистах и шаблоне; правила сохранены | | 2026-09-11 | Технический писатель (pi) | Исправлена ошибочная модель агента: финализация и коммиты в release/*, PR из неё в master/main; документы накапливаются заранее в обычных задачах | | 2026-09-11 | Технический писатель (pi) | Убраны «задолго до выпуска», повторы и избыточные пояснения; правила и команды сохранены | +| 2026-09-11 | Технический писатель (pi) | Описательные формулировки заменены действиями; уточнены объекты проверок, убран повтор процесса слияния из правил релизных документов | From ca6f408388411df31906e872b3c8988cd91c1114 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 07:12:04 +0700 Subject: [PATCH 09/40] =?UTF-8?q?docs(workflow):=20remove=20misplaced=20re?= =?UTF-8?q?porting=20rule=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BD=D0=B5=D1=83=D0=BC=D0=B5=D1=81=D1=82=D0=BD=D0=BE=D0=B5=20?= =?UTF-8?q?=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=BE=20=D0=BE=D1=82=D1=87?= =?UTF-8?q?=D1=91=D1=82=D0=BD=D0=BE=D1=81=D1=82=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/releases/index.md | 1 - todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index d3cdaa2..31a7f65 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -14,7 +14,6 @@ package: prikotov/git-workflow - Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. - При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. - Заполните обязательный `release-plan.md`: состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. -- Результаты проверок и выкладки записывайте в комментариях к запросу на слияние (Pull Request, PR) подготовки релиза. - Для срочного исправления (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 index e63ac0f..554870e 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-11 23:56:06 (1789170966) +completed: 2026-09-12 00:12:04 (1789171924) cancelled: value: V2 complexity: C2 @@ -149,3 +149,4 @@ git diff --check | 2026-09-11 | Технический писатель (pi) | Исправлена ошибочная модель агента: финализация и коммиты в release/*, PR из неё в master/main; документы накапливаются заранее в обычных задачах | | 2026-09-11 | Технический писатель (pi) | Убраны «задолго до выпуска», повторы и избыточные пояснения; правила и команды сохранены | | 2026-09-11 | Технический писатель (pi) | Описательные формулировки заменены действиями; уточнены объекты проверок, убран повтор процесса слияния из правил релизных документов | +| 2026-09-11 | Технический писатель (pi) | Из releases/index.md удалён дубль правила записи результатов в комментариях PR | From 8397a8ddae8d2a86dc3a71e95cc6fac02b3fe02b Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 07:21:06 +0700 Subject: [PATCH 10/40] =?UTF-8?q?docs(workflow):=20remove=20redundant=20di?= =?UTF-8?q?rectory=20rule=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?=D0=B8=D0=B7=D0=B1=D1=8B=D1=82=D0=BE=D1=87=D0=BD=D0=BE=D0=B5=20?= =?UTF-8?q?=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=BE=20=D0=BA=D0=B0=D1=82?= =?UTF-8?q?=D0=B0=D0=BB=D0=BE=D0=B3=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/releases/index.md | 1 - todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 31a7f65..de529cd 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -14,7 +14,6 @@ package: prikotov/git-workflow - Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. - При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. - Заполните обязательный `release-plan.md`: состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. -- Для срочного исправления (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 index 554870e..3c50168 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 00:12:04 (1789171924) +completed: 2026-09-12 00:21:06 (1789172466) cancelled: value: V2 complexity: C2 @@ -150,3 +150,4 @@ git diff --check | 2026-09-11 | Технический писатель (pi) | Убраны «задолго до выпуска», повторы и избыточные пояснения; правила и команды сохранены | | 2026-09-11 | Технический писатель (pi) | Описательные формулировки заменены действиями; уточнены объекты проверок, убран повтор процесса слияния из правил релизных документов | | 2026-09-11 | Технический писатель (pi) | Из releases/index.md удалён дубль правила записи результатов в комментариях PR | +| 2026-09-11 | Технический писатель (pi) | Из releases/index.md удалено избыточное указание о каталоге для срочных исправлений и патч-релизов | From a58a7a177c938b2950da4bc0e3e1b0849b64c0d2 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 07:29:05 +0700 Subject: [PATCH 11/40] =?UTF-8?q?docs(workflow):=20clarify=20release=20and?= =?UTF-8?q?=20hotfix=20bases=20/=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B1=D0=B0=D0=B7=D1=8B=20=D1=80=D0=B5=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B0=20=D0=B8=20=D1=81=D1=80=D0=BE=D1=87=D0=BD?= =?UTF-8?q?=D0=BE=D0=B3=D0=BE=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 2 +- docs/git-workflow/release.md | 2 +- docs/git-workflow/releases/index.md | 2 +- .../git-workflow/templates/release-plan.template.md | 13 ++++++------- .../TASK-docs-align-workflow-instructions.todo.md | 9 ++++++++- 5 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 04acefe..f0b8e64 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -67,7 +67,7 @@ git switch -c task/ ### Hotfix branch -По умолчанию hotfix создаётся от **текущего production tag** `vX.Y.Z`, а не от `master`. +Создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`. ```bash git fetch origin --tags --prune diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index ce35e93..5b9ab76 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -59,7 +59,7 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. -При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. +При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. В `release-plan.md` обязательно зафиксируйте: - состав релиза и его границы; diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index de529cd..9a80aec 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -12,7 +12,7 @@ package: prikotov/git-workflow ## Правила - Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. -- При финализации в `release/x.y` проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. +- При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. - Заполните обязательный `release-plan.md`: состав релиза, риски, миграции, порядок выкладки, последующие проверки и план срочного исправления при проблемах. ## Шаблон diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 86faaee..4946492 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,18 +1,17 @@ # План релиза vX.Y.Z -Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) проверьте полноту и актуальность плана. Результаты проверок и выкладки записывайте в комментариях к PR, не меняя одобренную ветку или тег. +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) проверьте полноту и актуальность плана. ## Метаданные - Тег релиза: `vX.Y.Z` - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: -- Линия релиза: `release/x.y` -- Сценарий: обычный релиз из основной ветки / срочное исправление от рабочего тега (указать одно) -- Основная ветка: `master` / `main` -- База: актуальная основная ветка / рабочий тег для срочного исправления -- Рабочая ветка финализации: `release/x.y` / `hotfix/x.y.z-` -- Цель PR: основная ветка +- Линия релиза: `x.y` +- Сценарий (указать одно): обычный релиз / срочное исправление +- База рабочей ветки: актуальная `master` / `main` для обычного релиза; тег текущей версии в рабочей среде для срочного исправления +- Рабочая ветка: `release/x.y` / `hotfix/x.y.z-` +- Цель PR: `master` / `main` - PR подготовки релиза: - Ответственный: - Плановая дата deploy: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 3c50168..6c38fdb 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 00:21:06 (1789172466) +completed: 2026-09-12 00:29:05 (1789172945) cancelled: value: V2 complexity: C2 @@ -124,6 +124,12 @@ git diff --check - Проверки: `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, ссылок, задачи и установки документов. Команды документации не изменены. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. @@ -151,3 +157,4 @@ git diff --check | 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 | From eda61cf046d8e352527a9c59e5b1555803ad5b06 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 07:42:10 +0700 Subject: [PATCH 12/40] =?UTF-8?q?docs(workflow):=20distinguish=20hotfix=20?= =?UTF-8?q?return=20PR=20/=20=D1=80=D0=B0=D0=B7=D0=B3=D1=80=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D1=87=D0=B8=D1=82=D1=8C=20PR=20=D0=B2=D0=BE=D0=B7=D0=B2?= =?UTF-8?q?=D1=80=D0=B0=D1=82=D0=B0=20=D1=81=D1=80=D0=BE=D1=87=D0=BD=D0=BE?= =?UTF-8?q?=D0=B3=D0=BE=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/pull-request.md | 2 +- docs/git-workflow/release.md | 2 +- docs/git-workflow/templates/release-plan.template.md | 7 ++++--- todo/done/TASK-docs-align-workflow-instructions.todo.md | 4 +++- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 9cb6dae..178a229 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -41,7 +41,7 @@ package: prikotov/git-workflow - Цель PR — основная ветка `master` или `main`. Далее она обозначается как `master`. - Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. - Финализация релиза: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. Не направляй PR в `release/*`. -- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку. Следуй [сценарию срочного исправления](release.md#hotfix-и-patch-release). +- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку для возврата исправления после выпуска. Следуй [сценарию срочного исправления](release.md#hotfix-и-patch-release). - До выпуска срочного исправления не синхронизируй его ветку с основной. Если для слияния нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. ## Обязательные проверки diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 5b9ab76..a9bed35 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -160,7 +160,7 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md 1. Определите текущий тег рабочей среды `vX.Y.Z` и создайте от него `hotfix/x.y.z-`. 2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в этой же ветке. -3. Выполните обязательные проверки, включая `make check` по правилам проекта и `make tests-e2e`. Откройте PR из `hotfix/*` в основную ветку, получите одобрение проверенного состояния и разрешение на выпуск. +3. Выполните обязательные проверки, включая `make check` по правилам проекта и `make tests-e2e`. Откройте PR из `hotfix/*` в основную ветку для возврата исправления после выпуска. Получите одобрение проверенного состояния `hotfix/*` и разрешение на выпуск. 4. Зафиксируйте SHA одобренного коммита `hotfix/*` и [опубликуйте тег](#3-создание-и-публикация-тега) на нём. Не используйте для срочного выпуска коммит основной ветки с другими изменениями. 5. Сразу после выпуска слейте PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если нужны доработки, повторите проверки и запросите новое одобрение. Не меняйте опубликованный тег. diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 4946492..f73d983 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -11,8 +11,8 @@ - Сценарий (указать одно): обычный релиз / срочное исправление - База рабочей ветки: актуальная `master` / `main` для обычного релиза; тег текущей версии в рабочей среде для срочного исправления - Рабочая ветка: `release/x.y` / `hotfix/x.y.z-` -- Цель PR: `master` / `main` -- PR подготовки релиза: +- PR подготовки обычного релиза (в `master` / `main`, слить до выпуска): +- PR возврата срочного исправления (в `master` / `main`, слить после выпуска): - Ответственный: - Плановая дата deploy: @@ -40,7 +40,7 @@ - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов - До публикации тега обычного релиза проверить, что PR из `release/x.y` слит в основную ветку - Проверить, что тег обычного релиза указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` -- Для срочного исправления проверить состав и коммит по отдельному сценарию в Git-регламенте проекта, а также план возврата исправления в основную ветку +- Для срочного исправления проверить, что тег указывает на одобренный коммит `hotfix/*` без невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: - Проверить готовность миграций, порядок их применения и риск окна несовместимости: @@ -48,6 +48,7 @@ ## План проверок после выкладки +- Для срочного исправления проверить, что PR возврата слит в `master` / `main` - Основные пользовательские сценарии и ожидаемые результаты: - Проверяемые логи и признаки ошибок: - Ожидаемое состояние очередей и обработчиков: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 6c38fdb..489f172 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 00:29:05 (1789172945) +completed: 2026-09-12 00:42:10 (1789173730) cancelled: value: V2 complexity: C2 @@ -129,6 +129,7 @@ git diff --check - В шаблоне разделены база рабочей ветки и цель PR; линия версии `x.y` больше не обозначается именем ветки `release/x.y`. Общие проверки документов применяются и к срочным исправлениям. - Выполнены 14 дополнительных проверок для `master` и `main`: после удаления релизной ветки локально и в удалённом репозитории команда из `branches.md` создаёт `hotfix/*` от тега рабочей версии, сохраняет её документы и исключает невыпущенные изменения основной ветки. Исходный тег не меняется. - Повторены 48 проверок обычного релиза, проверка Composer, ссылок, задачи и установки документов. Команды документации не изменены. +- Сценарий срочного исправления расширен до 34 проверок: конфликт с ушедшей вперёд основной веткой разрешается после публикации, исправление возвращается в неё вместе с новыми изменениями, оба опубликованных тега сохраняют исходное содержимое. После возврата рабочая ветка удаляется. ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. @@ -158,3 +159,4 @@ git diff --check | 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 возврата срочного исправления после выпуска; добавлены проверки коммита срочного выпуска и возврата исправления | From 26bd7733affddee80b44b74d9ab3a7a269cf5608 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 08:24:57 +0700 Subject: [PATCH 13/40] =?UTF-8?q?docs(release):=20restore=20pre-release=20?= =?UTF-8?q?hotfix=20PR=20/=20=D0=B2=D0=BE=D1=81=D1=81=D1=82=D0=B0=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=B8=D1=82=D1=8C=20PR=20=D1=81=D1=80=D0=BE=D1=87?= =?UTF-8?q?=D0=BD=D0=BE=D0=B3=D0=BE=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=B4=D0=BE=20=D0=B2=D1=8B?= =?UTF-8?q?=D0=BF=D1=83=D1=81=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 23 ++++++---- docs/git-workflow/pull-request.md | 16 ++++--- docs/git-workflow/release-checklists.md | 10 ++-- docs/git-workflow/release.md | 46 ++++++++++++++----- .../templates/release-plan.template.md | 11 +++-- ...K-docs-align-workflow-instructions.todo.md | 19 ++++++-- 6 files changed, 85 insertions(+), 40 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index f0b8e64..0b6d84b 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -17,15 +17,15 @@ package: prikotov/git-workflow - `master` или `main` — основная ветка разработки и источник обычных релизов. В примерах ниже используется `master`; для проекта с `main` замените имя в командах. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. -- `release/x.y` — рабочая ветка финализации релиза от актуальной основной ветки. +- `release/x.y` — ветка подготовки обычного релиза или срочного исправления выпущенной линии. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки. -- Одновременно поддерживается только одна активная `release/x.y`. +- Поддерживай одну ветку обычного релиза. Одновременно с ней допускается `release/x.y` выпущенной линии для срочного исправления. ## Общие правила - Вноси изменения в `master`/`main` только через PR. -- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. Не направляй PR в `release/*`. +- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй `release/x.y` выпущенной линии только через PR из `hotfix/*`. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. @@ -57,13 +57,15 @@ git switch -c task/ ### Release branch -Создай от актуальной основной ветки для финализации релиза: [процесс релиза](release.md#1-финализация-в-релизной-ветке). +Для обычного релиза создай ветку от актуальной основной: [процесс релиза](release.md#1-финализация-в-релизной-ветке). -Правила для `release/x.y`: +Правила для ветки обычного релиза: - коммить исправления, версии и релизные документы в этой ветке; - направляй PR из неё в основную ветку; слей PR до публикации тега; - PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y`; -- продолжай начатый выпуск в существующей ветке; перед новым выпуском закрой предыдущую линию, не перезаписывай ветку принудительно. +- продолжай начатый выпуск в существующей ветке; перед новым обычным выпуском заверши предыдущий, не перезаписывай ветку принудительно. + +Для срочного исправления используй `release/x.y` выпущенной линии. Удалённую ветку создай заново от рабочего тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза. ### Hotfix branch @@ -74,15 +76,16 @@ git fetch origin --tags --prune git switch -c hotfix/x.y.z- vX.Y.Z ``` -Подготовь исправление и файлы патч-релиза в этой ветке. Выпусти патч и слей PR в основную ветку по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y` выпущенной линии до создания нового тега. После выпуска верни патч-релиз отдельным PR из `release/x.y` в основную ветку по [сценарию срочного исправления](release.md#hotfix-и-patch-release). ## Синхронизация -- Синхронизируй `task/*` и `release/*` с основной веткой `master`/`main` до окончательного одобрения PR. -- До выпуска `hotfix/*` не подтягивай в неё ещё не выпущенные изменения основной ветки. После выпуска подготовь возврат исправления через PR в основную ветку. +- Синхронизируй `task/*` и ветку обычного релиза с основной веткой `master`/`main` до окончательного одобрения PR. +- Синхронизируй `hotfix/*` с целевой `release/x.y` выпущенной линии до окончательного одобрения PR. +- До срочного выпуска не подтягивай основную ветку в `hotfix/*` или `release/x.y` исправляемой линии. Адаптацию к основной ветке выполняй после выпуска при подготовке PR возврата. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. -В `task/*` или `release/*` получи актуальное состояние основной ветки: +Для обычной задачи или обычного релиза получи актуальное состояние основной ветки: ```bash base=master # Для проекта с main: base=main. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index 178a229..c325eea 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` или `main`), проходящий проверки и `Code Review`. +**Pull Request (PR)** — предложенный набор изменений из рабочей ветки в целевую, проходящий проверки и `Code Review`. ## Границы ответственности @@ -17,7 +17,7 @@ package: prikotov/git-workflow ## Правила - Вноси изменения в `master`/`main` только через PR. Коммить в рабочих ветках `task/*`, `release/*` и `hotfix/*` только по запросу пользователя. -- Одна задача — один PR, либо одна подзадача, если задача большая. +- Одна обычная задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. - Не добавляй в PR изменения "заодно". @@ -38,11 +38,12 @@ package: prikotov/git-workflow ## Выбор base branch -- Цель PR — основная ветка `master` или `main`. Далее она обозначается как `master`. +- Основная ветка проекта — `master` или `main`. Далее она обозначается как `master`. - Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. -- Финализация релиза: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. Не направляй PR в `release/*`. -- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в основную ветку для возврата исправления после выпуска. Следуй [сценарию срочного исправления](release.md#hotfix-и-patch-release). -- До выпуска срочного исправления не синхронизируй его ветку с основной. Если для слияния нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. +- Обычный релиз: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. +- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в `release/x.y` выпущенной линии до публикации нового тега. Создание удалённой ветки от тега описано в [сценарии срочного исправления](release.md#hotfix-и-patch-release). +- Возврат срочного исправления: отдельный PR из `release/x.y` выпущенной линии в основную ветку после выпуска. +- До срочного выпуска не синхронизируй `hotfix/*` и целевую `release/x.y` с основной веткой. Если для возврата нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. ## Обязательные проверки @@ -113,7 +114,8 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. -- Слей PR обычного релиза до публикации тега, PR срочного исправления — сразу после выпуска. +- Слей PR подготовки обычного релиза или срочного исправления до публикации тега. +- PR возврата срочного исправления из `release/x.y` в основную ветку слей после выпуска. ## После merge diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 0bebc02..1eb7524 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -29,9 +29,13 @@ package: prikotov/git-workflow - Определён текущий тег релиза на production `vX.Y.Z`. - Рабочая ветка срочного исправления `hotfix/x.y.z-` создана от тега рабочей среды, а не от ветки `master`. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; PR направлен в основную ветку, слияние запланировано сразу после выпуска. -- Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки успешны. -- Проверенное состояние одобрено, выпуск разрешён. Тег отмечает зафиксированный коммит `hotfix/*` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +- Цель PR — `release/x.y` выпущенной линии. Если ветка была удалена, она создана заново от рабочего тега; ветка следующего релиза не затронута. +- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y` завершена до одобрения. +- Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки и CI успешны. +- Проверенный PR из `hotfix/*` в `release/x.y` одобрен и слит через GitHub с подтверждением пользователя. +- Коммит слияния входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. +- Выпуск разрешён. Новый тег отмечает проверенный результат слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +- После выпуска запланирован отдельный PR возврата из `release/x.y` выпущенной линии в основную ветку; адаптация и конфликты не меняют опубликованный тег. ## Чеклист выкладки diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index a9bed35..6dd2095 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -9,11 +9,11 @@ package: prikotov/git-workflow ## Модель релизов - Финализируйте обычный релиз в `release/x.y` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. -- Направляйте запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку. -- После проверок и одобрения слейте PR. Поставьте тег на проверенный коммит слияния. +- Для обычного релиза направляйте запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку. +- После проверок и одобрения слейте PR обычного релиза. Поставьте тег на проверенный коммит слияния. - Изменяйте `master`/`main` только через PR. Коммитьте в рабочих ветках только по запросу пользователя. - Разворачивайте рабочую среду (production) по неизменяемому тегу `vX.Y.Z`, не по последнему коммиту ветки. -- Поддерживайте только одну активную `release/x.y`. +- Поддерживайте одну ветку обычного релиза. Для срочного исправления допускается отдельная `release/x.y` выпущенной линии. - Для срочного исправления от рабочего тега следуйте [отдельному сценарию](#hotfix-и-patch-release). ## SemVer и линии релиза @@ -97,7 +97,7 @@ git diff ### 1. Финализация в релизной ветке -Выберите версию по SemVer и создайте `release/x.y` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке. Перед новым выпуском завершите предыдущую линию по [правилам веток](branches.md#завершение); имя должно быть свободно локально и в `origin`, принудительная перезапись запрещена. +Выберите версию по SemVer и создайте `release/x.y` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке. Перед новым обычным выпуском завершите предыдущий по [правилам веток](branches.md#завершение); имя должно быть свободно локально и в `origin`, принудительная перезапись запрещена. Замените `x.y` номером линии: @@ -156,15 +156,38 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Hotfix и patch release -Не добавляйте в срочное исправление невыпущенные изменения основной ветки. +Определите текущий тег рабочей среды `vX.Y.Z`. Цель PR исправления — `release/x.y` этой выпущенной линии. Если ветка удалена локально и в `origin`, создайте её от рабочего тега: -1. Определите текущий тег рабочей среды `vX.Y.Z` и создайте от него `hotfix/x.y.z-`. -2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в этой же ветке. -3. Выполните обязательные проверки, включая `make check` по правилам проекта и `make tests-e2e`. Откройте PR из `hotfix/*` в основную ветку для возврата исправления после выпуска. Получите одобрение проверенного состояния `hotfix/*` и разрешение на выпуск. -4. Зафиксируйте SHA одобренного коммита `hotfix/*` и [опубликуйте тег](#3-создание-и-публикация-тега) на нём. Не используйте для срочного выпуска коммит основной ветки с другими изменениями. -5. Сразу после выпуска слейте PR в основную ветку по [правилам возврата изменений](pull-request.md#выбор-base-branch). Если нужны доработки, повторите проверки и запросите новое одобрение. Не меняйте опубликованный тег. +```bash +git fetch origin --tags --prune && + git switch -c release/x.y vX.Y.Z && + git push -u origin release/x.y +``` + +Если ветка существует, проверьте её базу и состав изменений. Не используйте ветку следующего релиза и не перезаписывайте её. При конфликте имени или несогласованных изменениях остановитесь и согласуйте состав и выбор ветки. + +Ветку следующего обычного релиза сохраняйте: она может существовать одновременно с веткой срочного выпуска. До выпуска не подтягивайте `master`/`main` в `hotfix/*` и `release/x.y` исправляемой линии. + +1. Создайте `hotfix/x.y.z-` от рабочего тега по [правилам веток](branches.md#hotfix-branch). +2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в `hotfix/*`. Убедитесь, что CI проекта запускается для целевой `release/x.y`. Откройте PR **из `hotfix/*` в `release/x.y` выпущенной линии**. +3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y`. Завершите все правки, выполните `make check` по правилам проекта и обязательный `make tests-e2e`; дождитесь успешных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. +4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`: + +```bash +release_branch=release/x.y +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" -- +``` + +При ошибке остановите выпуск. Доработки проведите через новый PR из `hotfix/*` в `release/x.y` с повторными проверками и одобрением. Изменение только SHA при совпадающем содержимом не требует полного повторного прогона или отдельного CI. + +5. После разрешения на выпуск [опубликуйте новый тег](#3-создание-и-публикация-тега) **на проверенном результате слияния**. Выпустите патч по этому тегу. +6. Сразу после выпуска откройте отдельный PR **из `release/x.y` выпущенной линии в `master`/`main`**. Выполните проверки, получите одобрение и подтверждение слияния. Если нужны адаптация или разрешение конфликтов, внесите их в эту `release/x.y` после выпуска и повторите проверки и одобрение. Не меняйте опубликованный тег. -Не закрывайте активную релизную ветку ради срочного исправления; перенесите исправление при следующей синхронизации с основной веткой. +Исправление попадёт в ветку следующего обычного релиза при её синхронизации с основной веткой. После выпуска и возврата исправления удалите рабочие ветки по [правилам завершения](branches.md#завершение). ## Recovery Policy @@ -176,5 +199,4 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Рекомендации команды - Для hotfix PR всегда явно фиксируйте merge-back plan. -- Не открывайте вторую `release/x.y`, пока не закрыта текущая line. - Для release и hotfix используйте чеклисты: [Чеклисты релиза и hotfix](release-checklists.md). diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index f73d983..2af4891 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,6 +1,6 @@ # План релиза vX.Y.Z -Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) проверьте полноту и актуальность плана. +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. ## Метаданные @@ -11,8 +11,8 @@ - Сценарий (указать одно): обычный релиз / срочное исправление - База рабочей ветки: актуальная `master` / `main` для обычного релиза; тег текущей версии в рабочей среде для срочного исправления - Рабочая ветка: `release/x.y` / `hotfix/x.y.z-` -- PR подготовки обычного релиза (в `master` / `main`, слить до выпуска): -- PR возврата срочного исправления (в `master` / `main`, слить после выпуска): +- PR подготовки релиза (слить до выпуска): +- PR возврата срочного исправления из `release/x.y` в `master` / `main` (после выпуска): - Ответственный: - Плановая дата deploy: @@ -40,7 +40,8 @@ - Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов - До публикации тега обычного релиза проверить, что PR из `release/x.y` слит в основную ветку - Проверить, что тег обычного релиза указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` -- Для срочного исправления проверить, что тег указывает на одобренный коммит `hotfix/*` без невыпущенных изменений основной ветки +- Для срочного исправления проверить, что PR из `hotfix/*` слит в `release/x.y` выпущенной линии до публикации нового тега +- Проверить, что тег срочного выпуска указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения: - Проверить готовность миграций, порядок их применения и риск окна несовместимости: @@ -48,7 +49,7 @@ ## План проверок после выкладки -- Для срочного исправления проверить, что PR возврата слит в `master` / `main` +- Для срочного исправления проверить, что PR возврата из `release/x.y` выпущенной линии слит в `master` / `main` - Основные пользовательские сценарии и ожидаемые результаты: - Проверяемые логи и признаки ошибок: - Ожидаемое состояние очередей и обработчиков: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 489f172..821d228 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 00:42:10 (1789173730) +completed: 2026-09-12 01:22:08 (1789176128) cancelled: value: V2 complexity: C2 @@ -49,7 +49,8 @@ status: done ## 3. Требования, MoSCoW (Requirements) ### 🔴 Обязательно (Must Have) - [x] Финализировать обычный релиз в `release/x.y` от актуальной основной ветки `master`/`main`; PR направлять из неё в основную ветку до выпуска. Срочное исправление от рабочего тега описывать отдельно. -- [x] Включать изменения в основную ветку только через PR; разрешить работу и коммиты в `release/*`, исключить входящие PR в неё и промежуточную ветку `task/prepare-release-*`. +- [x] Включать изменения в основную ветку только через PR; сохранить работу и коммиты в `release/*` обычного релиза без промежуточной `task/prepare-release-*`. Срочные исправления сливать через PR из `hotfix/*` в `release/x.y` выпущенной линии до нового тега. +- [x] Для срочного исправления создавать удалённую ветку выпущенной линии заново от рабочего тега; допускать её одновременно с веткой следующего обычного релиза. Возвращать выпущенный патч отдельным PR из `release/x.y` в основную ветку. - [x] Разрешить создавать и дополнять релизные документы заранее в рамках обычных задач; при финализации проверять накопленное, не заменять существующий план шаблоном. - [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. - [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. @@ -82,7 +83,7 @@ git diff --check ### Результат выполнения - Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. -- Документы релиза накапливаются в обычных задачах. Финализация выполняется в `release/x.y` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены; срочное исправление от рабочего тега описано отдельно. +- Документы релиза накапливаются в обычных задачах. Финализация обычного релиза выполняется в `release/x.y` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены. Срочное исправление проходит PR из `hotfix/*` в ветку выпущенной линии до нового тега, затем возвращается отдельным PR из этой ветки в основную. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Параметры `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`. @@ -97,6 +98,8 @@ git diff --check ### Доработка после замечаний пользователя +Ниже сохранена история промежуточных редакций. Порядок срочного исправления в них был изменён ошибочно; действующее решение приведено в разделе «Восстановление исходного маршрута срочного исправления». + - Задача возвращена в `review` перед исправлениями. Во взаимосвязанных документах явно различены имена рабочих веток, пути файлов и идентификаторы коммитов. - Сохранён обязательный предрелизный запуск `make tests-e2e`. Убрано добавленное требование полного повторного прогона и отдельного CI только из-за нового идентификатора коммита после слияния. Непроверенные изменения проверяются по правилам проекта. - Убрано предписание закрывать другую активную релизную ветку ради срочного исправления. Для закрытой ветки текущей рабочей версии не подставляется ветка следующего релиза; выбор целевой ветки согласуется с пользователем. @@ -131,8 +134,17 @@ git diff --check - Повторены 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, выпуски или сквозные тесты приложения. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. +- CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. - Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. ## 8. Источники (Sources) @@ -160,3 +172,4 @@ git diff --check | 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 в выпущенную линию до тега; подтверждено исключение для её сосуществования с подготовкой следующего релиза | From 5d287dfa7cca386e5a6c473e203cd7e409ee744d Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 08:58:03 +0700 Subject: [PATCH 14/40] =?UTF-8?q?docs(release):=20simplify=20plan=20metada?= =?UTF-8?q?ta=20/=20=D1=83=D0=BF=D1=80=D0=BE=D1=81=D1=82=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D0=BC=D0=B5=D1=82=D0=B0=D0=B4=D0=B0=D0=BD=D0=BD=D1=8B=D0=B5?= =?UTF-8?q?=20=D0=BF=D0=BB=D0=B0=D0=BD=D0=B0=20=D1=80=D0=B5=D0=BB=D0=B8?= =?UTF-8?q?=D0=B7=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/release-plan.template.md | 3 +-- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 2af4891..82180bf 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -7,12 +7,11 @@ - Тег релиза: `vX.Y.Z` - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: -- Линия релиза: `x.y` - Сценарий (указать одно): обычный релиз / срочное исправление - База рабочей ветки: актуальная `master` / `main` для обычного релиза; тег текущей версии в рабочей среде для срочного исправления - Рабочая ветка: `release/x.y` / `hotfix/x.y.z-` - PR подготовки релиза (слить до выпуска): -- PR возврата срочного исправления из `release/x.y` в `master` / `main` (после выпуска): +- PR включения срочного исправления в основную ветку (после выпуска): - Ответственный: - Плановая дата deploy: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 821d228..59a95c0 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 01:22:08 (1789176128) +completed: 2026-09-12 01:58:03 (1789178283) cancelled: value: V2 complexity: C2 @@ -173,3 +173,4 @@ git diff --check | 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 включения срочного исправления в основную ветку (после выпуска)» | From c95939d5d9a1af5a1f306b3ff83d8172f5329bb9 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 09:07:45 +0700 Subject: [PATCH 15/40] =?UTF-8?q?docs(release):=20make=20hotfix=20e2e=20op?= =?UTF-8?q?t-in=20/=20=D0=B7=D0=B0=D0=BF=D1=83=D1=81=D0=BA=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20=D1=81=D0=BA=D0=B2=D0=BE=D0=B7=D0=BD=D1=8B=D0=B5=20?= =?UTF-8?q?=D1=82=D0=B5=D1=81=D1=82=D1=8B=20=D1=81=D1=80=D0=BE=D1=87=D0=BD?= =?UTF-8?q?=D0=BE=D0=B3=D0=BE=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=B7=D0=B0=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D1=81=D1=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/deploy.md | 2 +- docs/git-workflow/release-checklists.md | 3 ++- docs/git-workflow/release.md | 4 +++- docs/git-workflow/templates/release-plan.template.md | 8 +++++--- .../TASK-docs-align-workflow-instructions.todo.md | 12 +++++++++++- 5 files changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index d344602..ff631a4 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -28,7 +28,7 @@ package: prikotov/git-workflow ## Рекомендуемый поток -1. Подготовить выпуск по [процессу релиза](release.md#выпуск-релиза) или [сценарию срочного исправления](release.md#hotfix-и-patch-release), пройти обязательные проверки, включая `make tests-e2e`, и опубликовать тег. +1. Подготовить выпуск по [процессу релиза](release.md#выпуск-релиза) или [сценарию срочного исправления](release.md#hotfix-и-patch-release), пройти обязательные проверки выбранного сценария и опубликовать тег. 2. Развернуть выбранный тег `vX.Y.Z` по инструкции выкладки проекта (runbook). 3. Проверить основные пользовательские сценарии, логи и метрики. 4. При проблеме остановить выкладку и выпустить срочное исправление (hotfix) или патч-релиз (patch release). diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index 1eb7524..aae9ac1 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -31,7 +31,8 @@ package: prikotov/git-workflow - Объём срочного исправления минимален и не тянет несвязанные изменения. - Цель PR — `release/x.y` выпущенной линии. Если ветка была удалена, она создана заново от рабочего тега; ветка следующего релиза не затронута. - Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y` завершена до одобрения. -- Перед срочным выпуском выполнены `make check` по правилам проекта и обязательный запуск `make tests-e2e`; проверки и CI успешны. +- Перед срочным выпуском выполнен `make check` по правилам проекта; проверки и CI успешны. +- Если пользователь явно запросил сквозные тесты, они выполнены успешно; без запроса не запускались. - Проверенный PR из `hotfix/*` в `release/x.y` одобрен и слит через GitHub с подтверждением пользователя. - Коммит слияния входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. - Выпуск разрешён. Новый тег отмечает проверенный результат слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 6dd2095..d9358de 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -168,9 +168,11 @@ git fetch origin --tags --prune && Ветку следующего обычного релиза сохраняйте: она может существовать одновременно с веткой срочного выпуска. До выпуска не подтягивайте `master`/`main` в `hotfix/*` и `release/x.y` исправляемой линии. +При срочном исправлении запускайте сквозные тесты только по явному запросу пользователя. Если затронут критический пользовательский сценарий, предложите точечный запуск вместо полного `make tests-e2e`. + 1. Создайте `hotfix/x.y.z-` от рабочего тега по [правилам веток](branches.md#hotfix-branch). 2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в `hotfix/*`. Убедитесь, что CI проекта запускается для целевой `release/x.y`. Откройте PR **из `hotfix/*` в `release/x.y` выпущенной линии**. -3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y`. Завершите все правки, выполните `make check` по правилам проекта и обязательный `make tests-e2e`; дождитесь успешных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. +3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y`. Завершите все правки, выполните `make check` по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. 4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`: ```bash diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 82180bf..780753e 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -36,14 +36,16 @@ ## План проверок перед выкладкой -- Выполнить `make check` по правилам проекта и обязательный предрелизный запуск `make tests-e2e`; дождаться успешных результатов +- Выполнить `make check` по правилам проекта; дождаться успешного результата +- Для обычного релиза обязательно выполнить `make tests-e2e`; дождаться успешного результата +- Для срочного исправления запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок - До публикации тега обычного релиза проверить, что PR из `release/x.y` слит в основную ветку - Проверить, что тег обычного релиза указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` - Для срочного исправления проверить, что PR из `hotfix/*` слит в `release/x.y` выпущенной линии до публикации нового тега - Проверить, что тег срочного выпуска указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` -- Проверить необходимые изменения переменных окружения: -- Проверить готовность миграций, порядок их применения и риск окна несовместимости: +- Проверить необходимые изменения переменных окружения +- Проверить готовность миграций, порядок их применения и риск окна несовместимости - Команды проверки работоспособности (health-check) и ожидаемые результаты: ## План проверок после выкладки diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 59a95c0..86b8d1c 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 01:58:03 (1789178283) +completed: 2026-09-12 02:07:21 (1789178841) cancelled: value: V2 complexity: C2 @@ -55,6 +55,7 @@ status: done - [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. - [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. - [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. +- [x] По подтверждённому запросу пользователя оставить сквозные тесты обязательными для обычного релиза, а для срочного исправления запускать только по явному запросу. Не менять требования к `make check` и CI. - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. ### ⚫ Won't Have (Не будем делать) @@ -85,6 +86,7 @@ git diff --check - Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. - Документы релиза накапливаются в обычных задачах. Финализация обычного релиза выполняется в `release/x.y` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены. Срочное исправление проходит PR из `hotfix/*` в ветку выпущенной линии до нового тега, затем возвращается отдельным PR из этой ветки в основную. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. +- Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к `make check` и 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 в установленной копии, ошибок нет. @@ -142,6 +144,13 @@ git diff --check - Для проверки выбран именно согласованный маршрут: неслитый `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 проверок обычного релиза. Сквозные тесты приложения не запускались: изменена только документация. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -174,3 +183,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | В шаблоне и регламенте различены PR подготовки обычного релиза и PR возврата срочного исправления после выпуска; добавлены проверки коммита срочного выпуска и возврата исправления | | 2026-09-12 | Технический писатель (pi) | Восстановлен ошибочно изменённый агентом маршрут срочного исправления через PR в выпущенную линию до тега; подтверждено исключение для её сосуществования с подготовкой следующего релиза | | 2026-09-12 | Технический писатель (pi) | По замечаниям пользователя удалено поле «Линия релиза»; поле ссылки на PR названо «PR включения срочного исправления в основную ветку (после выпуска)» | +| 2026-09-12 | Технический писатель (pi) | По подтверждённому запросу сквозные тесты срочного исправления запускаются только по запросу пользователя; для обычного релиза обязательность сохранена. Исправлены два лишних двоеточия у готовых инструкций шаблона | From fb2051e090195852ee11eba2a4b4f539bd1cf778 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 20:15:39 +0700 Subject: [PATCH 16/40] =?UTF-8?q?docs(release):=20split=20plan=20templates?= =?UTF-8?q?=20/=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD=D1=8B=20=D0=BF=D0=BB?= =?UTF-8?q?=D0=B0=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +- docs/git-workflow/release.md | 2 +- docs/git-workflow/releases/index.md | 8 ++- .../templates/hotfix-release-plan.template.md | 64 +++++++++++++++++++ .../templates/release-plan.template.md | 18 ++---- ...K-docs-align-workflow-instructions.todo.md | 14 +++- 6 files changed, 90 insertions(+), 19 deletions(-) create mode 100644 docs/git-workflow/templates/hotfix-release-plan.template.md diff --git a/AGENTS.md b/AGENTS.md index 77f0d95..eae7b65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,8 @@ docs/ releases/ # Описание артефактов релиза index.md templates/ - release-plan.template.md # Шаблон плана релиза + release-plan.template.md # Шаблон плана обычного релиза + hotfix-release-plan.template.md # Шаблон плана срочного исправления todo/ # Внутренние задачи по доработке пакета ``` diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index d9358de..72c8737 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -59,7 +59,7 @@ git commit -m "chore(release): prepare vX.Y.Z / подготовить vX.Y.Z" Создавайте и дополняйте документы в `docs/releases/vX.Y.Z/` по мере выполнения задач. Записывайте действия до и после релиза. -При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по [шаблону](./templates/release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. +При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. Если `release-plan.md` отсутствует, создайте его по шаблону [обычного релиза](./templates/release-plan.template.md) или [срочного исправления](./templates/hotfix-release-plan.template.md); существующий план не перезаписывайте шаблоном. Заполните план до одобрения PR. Не начинайте выкладку без заполненного плана. В `release-plan.md` обязательно зафиксируйте: - состав релиза и его границы; diff --git a/docs/git-workflow/releases/index.md b/docs/git-workflow/releases/index.md index 9a80aec..a2c9524 100644 --- a/docs/git-workflow/releases/index.md +++ b/docs/git-workflow/releases/index.md @@ -6,7 +6,8 @@ package: prikotov/git-workflow ## Структура -- `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` — заполненный план релиза для конкретного тега релиза. ## Правила @@ -15,6 +16,7 @@ package: prikotov/git-workflow - При финализации релиза проверьте полноту документов и их соответствие составу релиза, внесите необходимые изменения. - Заполните обязательный `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..793bb50 --- /dev/null +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -0,0 +1,64 @@ +# План срочного исправления vX.Y.Z + +Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) срочного исправления проверьте полноту и актуальность плана. + +## Метаданные + +- Тег релиза: `vX.Y.Z` +- Тип повышения версии: `patch` +- Обоснование выбранной версии: +- База рабочей ветки (тег текущей версии в рабочей среде): +- Рабочая ветка: `hotfix/x.y.z-` +- PR срочного исправления в `release/x.y` (слить до выпуска): +- PR включения срочного исправления в основную ветку (после выпуска): +- Ответственный: +- Плановая дата deploy: + +## Состав + +- Включённые PR: +- Включённые задачи: +- Вне состава релиза: + +## Риски + +- Основные риски: +- Наличие миграций данных: +- Порядок применения миграций: +- Риск окна несовместимости: +- Замечания по обратной совместимости: + +## Порядок deploy + +1. Web +2. Workers + +## План проверок перед выкладкой + +- Выполнить `make check` по правилам проекта; дождаться успешного результата +- Запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок +- До публикации тега проверить, что PR из `hotfix/*` слит в `release/x.y` выпущенной линии +- Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки +- Убедиться, что согласованный тег опубликован в `origin` +- Проверить необходимые изменения переменных окружения +- Проверить готовность миграций, порядок их применения и риск окна несовместимости +- Команды проверки работоспособности (health-check) и ожидаемые результаты: + +## План проверок после выкладки + +- Проверить, что исправление включено в `master` / `main` через PR из `release/x.y` выпущенной линии +- Основные пользовательские сценарии и ожидаемые результаты: +- Проверяемые логи и признаки ошибок: +- Ожидаемое состояние очередей и обработчиков: +- Способ проверки версии сборки и идентификатора коммита (SHA): + +## Действия при проблеме после релиза + +- Откат: не используется +- Стратегия исправления: `hotfix` / `patch release` +- Ответственный инженер: +- Канал коммуникации / задача: + +## Заметки + +- Дополнительные инструкции: diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 780753e..e1f2fdc 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,4 +1,4 @@ -# План релиза vX.Y.Z +# План обычного релиза vX.Y.Z Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. @@ -7,11 +7,9 @@ - Тег релиза: `vX.Y.Z` - Тип повышения версии (указать одно: `major`, `minor` или `patch`): - Обоснование выбранной версии: -- Сценарий (указать одно): обычный релиз / срочное исправление -- База рабочей ветки: актуальная `master` / `main` для обычного релиза; тег текущей версии в рабочей среде для срочного исправления -- Рабочая ветка: `release/x.y` / `hotfix/x.y.z-` +- База рабочей ветки: актуальная `master` / `main` +- Рабочая ветка: `release/x.y` - PR подготовки релиза (слить до выпуска): -- PR включения срочного исправления в основную ветку (после выпуска): - Ответственный: - Плановая дата deploy: @@ -37,12 +35,9 @@ ## План проверок перед выкладкой - Выполнить `make check` по правилам проекта; дождаться успешного результата -- Для обычного релиза обязательно выполнить `make tests-e2e`; дождаться успешного результата -- Для срочного исправления запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок -- До публикации тега обычного релиза проверить, что PR из `release/x.y` слит в основную ветку -- Проверить, что тег обычного релиза указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` -- Для срочного исправления проверить, что PR из `hotfix/*` слит в `release/x.y` выпущенной линии до публикации нового тега -- Проверить, что тег срочного выпуска указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки +- Обязательно выполнить `make tests-e2e`; дождаться успешного результата +- До публикации тега проверить, что PR из `release/x.y` слит в основную ветку +- Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения - Проверить готовность миграций, порядок их применения и риск окна несовместимости @@ -50,7 +45,6 @@ ## План проверок после выкладки -- Для срочного исправления проверить, что PR возврата из `release/x.y` выпущенной линии слит в `master` / `main` - Основные пользовательские сценарии и ожидаемые результаты: - Проверяемые логи и признаки ошибок: - Ожидаемое состояние очередей и обработчиков: diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 86b8d1c..f593571 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 02:07:21 (1789178841) +completed: 2026-09-12 13:14:11 (1789218851) cancelled: value: V2 complexity: C2 @@ -58,6 +58,7 @@ status: done - [x] По подтверждённому запросу пользователя оставить сквозные тесты обязательными для обычного релиза, а для срочного исправления запускать только по явному запросу. Не менять требования к `make check` и CI. - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. +- [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -83,7 +84,7 @@ git diff --check ### Результат выполнения -- Согласованы `branches.md`, `commits.md`, `pull-request.md`, `release.md`, `release-checklists.md`, `deploy.md`, `releases/index.md` и `templates/release-plan.template.md` в `docs/git-workflow/`. +- Согласованы `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` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены. Срочное исправление проходит PR из `hotfix/*` в ветку выпущенной линии до нового тега, затем возвращается отдельным PR из этой ветки в основную. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к `make check` и CI сохранены. @@ -151,6 +152,14 @@ git diff --check - Двоеточия в шаблоне обозначают поля для заполнения. У двух готовых инструкций проверки окружения и миграций они были лишними и удалены. Двоеточия перед вложенными списками и примерами в остальных документах корректны и сохранены. - Проверки: `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 проверок обычного релиза. Изменена только документация; тесты приложения не запускались. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -184,3 +193,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | Восстановлен ошибочно изменённый агентом маршрут срочного исправления через PR в выпущенную линию до тега; подтверждено исключение для её сосуществования с подготовкой следующего релиза | | 2026-09-12 | Технический писатель (pi) | По замечаниям пользователя удалено поле «Линия релиза»; поле ссылки на PR названо «PR включения срочного исправления в основную ветку (после выпуска)» | | 2026-09-12 | Технический писатель (pi) | По подтверждённому запросу сквозные тесты срочного исправления запускаются только по запросу пользователя; для обычного релиза обязательность сохранена. Исправлены два лишних двоеточия у готовых инструкций шаблона | +| 2026-09-12 | Технический писатель (pi) | Разделены шаблоны обычного релиза и срочного исправления; обновлены ссылки и структура пакета без изменения регламента выпуска | From dc1ec8b742bb5db7dc49f4aadda43df320ec2c48 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 20:34:47 +0700 Subject: [PATCH 17/40] =?UTF-8?q?docs(release):=20add=20field=20hints=20/?= =?UTF-8?q?=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82=D1=8C=20=D0=BF?= =?UTF-8?q?=D0=BE=D0=B4=D1=81=D0=BA=D0=B0=D0=B7=D0=BA=D0=B8=20=D0=BA=20?= =?UTF-8?q?=D0=BF=D0=BE=D0=BB=D1=8F=D0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../templates/hotfix-release-plan.template.md | 46 ++++++++++--------- .../templates/release-plan.template.md | 44 +++++++++--------- ...K-docs-align-workflow-instructions.todo.md | 10 +++- 3 files changed, 56 insertions(+), 44 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 793bb50..73a3dcf 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -2,31 +2,33 @@ Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) срочного исправления проверьте полноту и актуальность плана. +Заменяйте подсказки в квадратных скобках данными выпуска по мере подготовки и выполнения плана. + ## Метаданные - Тег релиза: `vX.Y.Z` - Тип повышения версии: `patch` -- Обоснование выбранной версии: -- База рабочей ветки (тег текущей версии в рабочей среде): +- Обоснование выбранной версии: [причина повышения версии с учётом совместимости] +- База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии] - Рабочая ветка: `hotfix/x.y.z-` -- PR срочного исправления в `release/x.y` (слить до выпуска): -- PR включения срочного исправления в основную ветку (после выпуска): -- Ответственный: -- Плановая дата deploy: +- PR срочного исправления в `release/x.y` (слить до выпуска): [ссылка на PR] +- PR включения срочного исправления в основную ветку (после выпуска): [ссылка на PR после его создания] +- Ответственный: [имя или ссылка на профиль] +- Плановая дата deploy: [дата, время и часовой пояс] ## Состав -- Включённые PR: -- Включённые задачи: -- Вне состава релиза: +- Включённые PR: [ссылки на PR] +- Включённые задачи: [ссылки на задачи] +- Вне состава релиза: [изменения, которые не войдут в выпуск] ## Риски -- Основные риски: -- Наличие миграций данных: -- Порядок применения миграций: -- Риск окна несовместимости: -- Замечания по обратной совместимости: +- Основные риски: [риски выпуска и меры их снижения] +- Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] +- Порядок применения миграций: [команды и последовательность применения] +- Риск окна несовместимости: [несовместимые компоненты, длительность окна и меры защиты] +- Замечания по обратной совместимости: [затронутые контракты и необходимые действия] ## Порядок deploy @@ -42,23 +44,23 @@ - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения - Проверить готовность миграций, порядок их применения и риск окна несовместимости -- Команды проверки работоспособности (health-check) и ожидаемые результаты: +- Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] ## План проверок после выкладки - Проверить, что исправление включено в `master` / `main` через PR из `release/x.y` выпущенной линии -- Основные пользовательские сценарии и ожидаемые результаты: -- Проверяемые логи и признаки ошибок: -- Ожидаемое состояние очередей и обработчиков: -- Способ проверки версии сборки и идентификатора коммита (SHA): +- Основные пользовательские сценарии и ожидаемые результаты: [шаги проверки и признаки успеха] +- Проверяемые логи и признаки ошибок: [источники логов и сообщения, требующие реакции] +- Ожидаемое состояние очередей и обработчиков: [проверяемые показатели и допустимые значения] +- Способ проверки версии сборки и идентификатора коммита (SHA): [команда или место проверки и ожидаемые значения] ## Действия при проблеме после релиза - Откат: не используется - Стратегия исправления: `hotfix` / `patch release` -- Ответственный инженер: -- Канал коммуникации / задача: +- Ответственный инженер: [имя или ссылка на профиль] +- Канал коммуникации / задача: [ссылка на канал или задачу для координации исправления] ## Заметки -- Дополнительные инструкции: +- Дополнительные инструкции: [особые действия для этого выпуска] diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index e1f2fdc..45a6630 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -2,30 +2,32 @@ Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. +Заменяйте подсказки в квадратных скобках данными выпуска по мере подготовки и выполнения плана. + ## Метаданные - Тег релиза: `vX.Y.Z` -- Тип повышения версии (указать одно: `major`, `minor` или `patch`): -- Обоснование выбранной версии: +- Тип повышения версии (указать одно: `major`, `minor` или `patch`): [выбранный тип] +- Обоснование выбранной версии: [причина повышения версии с учётом совместимости] - База рабочей ветки: актуальная `master` / `main` - Рабочая ветка: `release/x.y` -- PR подготовки релиза (слить до выпуска): -- Ответственный: -- Плановая дата deploy: +- PR подготовки релиза (слить до выпуска): [ссылка на PR] +- Ответственный: [имя или ссылка на профиль] +- Плановая дата deploy: [дата, время и часовой пояс] ## Состав -- Включённые PR: -- Включённые задачи: -- Вне состава релиза: +- Включённые PR: [ссылки на PR] +- Включённые задачи: [ссылки на задачи] +- Вне состава релиза: [изменения, которые не войдут в выпуск] ## Риски -- Основные риски: -- Наличие миграций данных: -- Порядок применения миграций: -- Риск окна несовместимости: -- Замечания по обратной совместимости: +- Основные риски: [риски выпуска и меры их снижения] +- Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] +- Порядок применения миграций: [команды и последовательность применения] +- Риск окна несовместимости: [несовместимые компоненты, длительность окна и меры защиты] +- Замечания по обратной совместимости: [затронутые контракты и необходимые действия] ## Порядок deploy @@ -41,22 +43,22 @@ - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения - Проверить готовность миграций, порядок их применения и риск окна несовместимости -- Команды проверки работоспособности (health-check) и ожидаемые результаты: +- Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] ## План проверок после выкладки -- Основные пользовательские сценарии и ожидаемые результаты: -- Проверяемые логи и признаки ошибок: -- Ожидаемое состояние очередей и обработчиков: -- Способ проверки версии сборки и идентификатора коммита (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 index f593571..6d41f4f 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 13:14:11 (1789218851) +completed: 2026-09-12 13:34:11 (1789220051) cancelled: value: V2 complexity: C2 @@ -59,6 +59,7 @@ status: done - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. +- [x] В обоих шаблонах снабдить пустые поля предметными подсказками и пояснить, что их нужно заменять данными выпуска. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -160,6 +161,12 @@ git diff --check - Проверены разделение сценариев, сохранность общих полей, условия сквозных тестов и оба маршрута PR. Установка и повторная установка: 12 документов совпадают с исходниками. При обновлении без `--force` существующие документы сохранены, новый шаблон добавлен; с `--force` обновлены все конвенции, заполненный план релиза не затронут. - `composer validate --strict`, валидация задачи, ссылки и `git diff --check` — успешно. Повторены 394 проверки Git-модели срочного исправления и 48 проверок обычного релиза. Изменена только документация; тесты приложения не запускались. +### Подсказки для заполнения полей + +- По замечанию пользователя после двоеточий добавлены 43 подсказки в квадратных скобках: 21 в обычном плане и 22 в срочном. В начале обоих шаблонов указано заменять подсказки данными выпуска по мере подготовки и выполнения плана. +- Проверено отсутствие пустых полей и совпадение подсказок у общих полей. После удаления подсказок и вводной строки оба шаблона полностью совпадают с редакцией `fb2051e`: правила и проверки выпуска не изменены. +- Проверки Composer, задачи, ссылок и форматирования — успешно. Установка и повторная установка: все 12 документов совпадают с исходниками. Тесты приложения не запускались: только документация. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -194,3 +201,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | По замечаниям пользователя удалено поле «Линия релиза»; поле ссылки на PR названо «PR включения срочного исправления в основную ветку (после выпуска)» | | 2026-09-12 | Технический писатель (pi) | По подтверждённому запросу сквозные тесты срочного исправления запускаются только по запросу пользователя; для обычного релиза обязательность сохранена. Исправлены два лишних двоеточия у готовых инструкций шаблона | | 2026-09-12 | Технический писатель (pi) | Разделены шаблоны обычного релиза и срочного исправления; обновлены ссылки и структура пакета без изменения регламента выпуска | +| 2026-09-12 | Технический писатель (pi) | Пустые поля обоих шаблонов дополнены предметными подсказками; добавлена инструкция по их замене данными выпуска | From c8953a027e884b1373b1d992aef48085ffd42941 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 20:41:56 +0700 Subject: [PATCH 18/40] =?UTF-8?q?docs(release):=20unify=20field=20hints=20?= =?UTF-8?q?/=20=D1=83=D0=BD=D0=B8=D1=84=D0=B8=D1=86=D0=B8=D1=80=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D1=82=D1=8C=20=D0=BF=D0=BE=D0=B4=D1=81=D0=BA=D0=B0?= =?UTF-8?q?=D0=B7=D0=BA=D0=B8=20=D0=BF=D0=BE=D0=BB=D0=B5=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../templates/hotfix-release-plan.template.md | 10 +++++----- docs/git-workflow/templates/release-plan.template.md | 12 ++++++------ .../TASK-docs-align-workflow-instructions.todo.md | 11 +++++++++-- 3 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 73a3dcf..d578392 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -1,4 +1,4 @@ -# План срочного исправления vX.Y.Z +# План срочного исправления [тег релиза] Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) срочного исправления проверьте полноту и актуальность плана. @@ -6,11 +6,11 @@ ## Метаданные -- Тег релиза: `vX.Y.Z` +- Тег релиза: [тег в формате `vX.Y.Z`] - Тип повышения версии: `patch` - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] -- База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии] -- Рабочая ветка: `hotfix/x.y.z-` +- База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] +- Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] - PR срочного исправления в `release/x.y` (слить до выпуска): [ссылка на PR] - PR включения срочного исправления в основную ветку (после выпуска): [ссылка на PR после его создания] - Ответственный: [имя или ссылка на профиль] @@ -57,7 +57,7 @@ ## Действия при проблеме после релиза - Откат: не используется -- Стратегия исправления: `hotfix` / `patch release` +- Стратегия исправления: [выбранная стратегия: `hotfix` или `patch release`] - Ответственный инженер: [имя или ссылка на профиль] - Канал коммуникации / задача: [ссылка на канал или задачу для координации исправления] diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 45a6630..e8d4e51 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -1,4 +1,4 @@ -# План обычного релиза vX.Y.Z +# План обычного релиза [тег релиза] Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. @@ -6,11 +6,11 @@ ## Метаданные -- Тег релиза: `vX.Y.Z` -- Тип повышения версии (указать одно: `major`, `minor` или `patch`): [выбранный тип] +- Тег релиза: [тег в формате `vX.Y.Z`] +- Тип повышения версии: [`major`, `minor` или `patch`] - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] -- База рабочей ветки: актуальная `master` / `main` -- Рабочая ветка: `release/x.y` +- База рабочей ветки: [актуальная основная ветка: `master` или `main`] +- Рабочая ветка: [ветка в формате `release/x.y`] - PR подготовки релиза (слить до выпуска): [ссылка на PR] - Ответственный: [имя или ссылка на профиль] - Плановая дата deploy: [дата, время и часовой пояс] @@ -55,7 +55,7 @@ ## Действия при проблеме после релиза - Откат: не используется -- Стратегия исправления: `hotfix` / `patch release` +- Стратегия исправления: [выбранная стратегия: `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 index 6d41f4f..e5e30dd 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 13:34:11 (1789220051) +completed: 2026-09-12 13:41:26 (1789220486) cancelled: value: V2 complexity: C2 @@ -59,7 +59,7 @@ status: done - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. -- [x] В обоих шаблонах снабдить пустые поля предметными подсказками и пояснить, что их нужно заменять данными выпуска. +- [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками и пояснить, что их нужно заменять данными выпуска. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -167,6 +167,12 @@ git diff --check - Проверено отсутствие пустых полей и совпадение подсказок у общих полей. После удаления подсказок и вводной строки оба шаблона полностью совпадают с редакцией `fb2051e`: правила и проверки выпуска не изменены. - Проверки Composer, задачи, ссылок и форматирования — успешно. Установка и повторная установка: все 12 документов совпадают с исходниками. Тесты приложения не запускались: только документация. +### Единый формат всех изменяемых значений + +- Исправлена повторная ошибка агента: предыдущая проверка охватывала только пустые поля и пропустила тег, названия веток и другие заменяемые значения. Все 50 изменяемых полей и оба заголовка теперь используют подсказки в квадратных скобках. +- Фиксированные правила — повышение только `patch` для срочного исправления и отказ от отката — сохранены. Разделы проверок до и после выкладки дословно совпадают с `dc1ec8b`; порядок выпуска не менялся. +- Проверены все поля, а не только прежние пустые строки; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование — успешно. Изменена только документация. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -202,3 +208,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | По подтверждённому запросу сквозные тесты срочного исправления запускаются только по запросу пользователя; для обычного релиза обязательность сохранена. Исправлены два лишних двоеточия у готовых инструкций шаблона | | 2026-09-12 | Технический писатель (pi) | Разделены шаблоны обычного релиза и срочного исправления; обновлены ссылки и структура пакета без изменения регламента выпуска | | 2026-09-12 | Технический писатель (pi) | Пустые поля обоих шаблонов дополнены предметными подсказками; добавлена инструкция по их замене данными выпуска | +| 2026-09-12 | Технический писатель (pi) | Исправлена неполнота предыдущей правки: все изменяемые поля, включая тег, ветки и заголовки, приведены к единому формату подсказок | From 2a61688257d35ea32b3be3c5e8d225861c123e5a Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 20:48:13 +0700 Subject: [PATCH 19/40] =?UTF-8?q?docs(release):=20clarify=20hotfix=20kind?= =?UTF-8?q?=20/=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8=D1=82=D1=8C=20?= =?UTF-8?q?=D0=B2=D0=B8=D0=B4=20=D1=81=D1=80=D0=BE=D1=87=D0=BD=D0=BE=D0=B3?= =?UTF-8?q?=D0=BE=20=D0=B2=D1=8B=D0=BF=D1=83=D1=81=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../templates/hotfix-release-plan.template.md | 4 +--- docs/git-workflow/templates/release-plan.template.md | 2 -- .../done/TASK-docs-align-workflow-instructions.todo.md | 10 ++++++++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index d578392..0566432 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -2,12 +2,10 @@ Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) срочного исправления проверьте полноту и актуальность плана. -Заменяйте подсказки в квадратных скобках данными выпуска по мере подготовки и выполнения плана. - ## Метаданные - Тег релиза: [тег в формате `vX.Y.Z`] -- Тип повышения версии: `patch` +- Тип выпуска: `hotfix` - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] - База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] - Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index e8d4e51..3877c20 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -2,8 +2,6 @@ Дополняйте план по мере выполнения задач. До одобрения PR (запроса на слияние) подготовки релиза проверьте полноту и актуальность плана. -Заменяйте подсказки в квадратных скобках данными выпуска по мере подготовки и выполнения плана. - ## Метаданные - Тег релиза: [тег в формате `vX.Y.Z`] diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index e5e30dd..b6f455e 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 13:41:26 (1789220486) +completed: 2026-09-12 13:47:59 (1789220879) cancelled: value: V2 complexity: C2 @@ -59,7 +59,7 @@ status: done - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. -- [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками и пояснить, что их нужно заменять данными выпуска. +- [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками без отдельной инструкции по их заполнению. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -173,6 +173,11 @@ git diff --check - Фиксированные правила — повышение только `patch` для срочного исправления и отказ от отката — сохранены. Разделы проверок до и после выкладки дословно совпадают с `dc1ec8b`; порядок выпуска не менялся. - Проверены все поля, а не только прежние пустые строки; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование — успешно. Изменена только документация. +### Удаление избыточной инструкции и уточнение вида выпуска + +- По замечанию пользователя из обоих шаблонов удалена инструкция о замене подсказок. В плане срочного исправления поле заменено на «Тип выпуска: `hotfix`»; вид выпуска больше не обозначается уровнем повышения версии. +- Сравнение с `c8953a0` подтвердило отсутствие других изменений шаблонов. Все 50 изменяемых полей и оба заголовка сохранены; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование проверены успешно. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -209,3 +214,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | Разделены шаблоны обычного релиза и срочного исправления; обновлены ссылки и структура пакета без изменения регламента выпуска | | 2026-09-12 | Технический писатель (pi) | Пустые поля обоих шаблонов дополнены предметными подсказками; добавлена инструкция по их замене данными выпуска | | 2026-09-12 | Технический писатель (pi) | Исправлена неполнота предыдущей правки: все изменяемые поля, включая тег, ветки и заголовки, приведены к единому формату подсказок | +| 2026-09-12 | Технический писатель (pi) | Удалена избыточная инструкция по заполнению; в плане срочного исправления указан тип выпуска hotfix вместо уровня повышения версии | From 3d87bd93eefba25761b093d4f58d335f174c4443 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 21:56:00 +0700 Subject: [PATCH 20/40] =?UTF-8?q?docs(branches):=20resolve=20default=20bra?= =?UTF-8?q?nch=20/=20=D0=BE=D0=BF=D1=80=D0=B5=D0=B4=D0=B5=D0=BB=D1=8F?= =?UTF-8?q?=D1=82=D1=8C=20=D0=BE=D1=81=D0=BD=D0=BE=D0=B2=D0=BD=D1=83=D1=8E?= =?UTF-8?q?=20=D0=B2=D0=B5=D1=82=D0=BA=D1=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 23 +++++++++++-------- ...K-docs-align-workflow-instructions.todo.md | 10 +++++++- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 0b6d84b..02ba01c 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -15,7 +15,7 @@ package: prikotov/git-workflow ## Целевая модель -- `master` или `main` — основная ветка разработки и источник обычных релизов. В примерах ниже используется `master`; для проекта с `main` замените имя в командах. +- Основная ветка — ветка по умолчанию репозитория и источник обычных релизов; на неё указывает `origin/HEAD`. - `task/` — рабочая ветка для feature, bugfix, docs и рефакторинга. - `release/x.y` — ветка подготовки обычного релиза или срочного исправления выпущенной линии. - `hotfix/x.y.z-` — срочный patch для уже выкаченного production release. @@ -24,7 +24,7 @@ package: prikotov/git-workflow ## Общие правила -- Вноси изменения в `master`/`main` только через PR. +- Вноси изменения в основную ветку только через PR. - Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй `release/x.y` выпущенной линии только через PR из `hotfix/*`. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. @@ -47,11 +47,14 @@ package: prikotov/git-workflow ### Task branch -Для обычных задач база и цель PR — основная ветка `master` (либо `main`). Документы будущего релиза можно дополнять в этих же задачах. +Для обычных задач база и цель PR — основная ветка. Документы будущего релиза можно дополнять в этих же задачах. ```bash -git switch master -git pull --ff-only origin master +git fetch origin && +git remote set-head origin --auto && +base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && +git switch "${base#origin/}" && +git pull --ff-only origin "${base#origin/}" && git switch -c task/ ``` @@ -80,7 +83,7 @@ git switch -c hotfix/x.y.z- vX.Y.Z ## Синхронизация -- Синхронизируй `task/*` и ветку обычного релиза с основной веткой `master`/`main` до окончательного одобрения PR. +- Синхронизируй `task/*` и ветку обычного релиза с основной веткой до окончательного одобрения PR. - Синхронизируй `hotfix/*` с целевой `release/x.y` выпущенной линии до окончательного одобрения PR. - До срочного выпуска не подтягивай основную ветку в `hotfix/*` или `release/x.y` исправляемой линии. Адаптацию к основной ветке выполняй после выпуска при подготовке PR возврата. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. @@ -88,20 +91,20 @@ git switch -c hotfix/x.y.z- vX.Y.Z Для обычной задачи или обычного релиза получи актуальное состояние основной ветки: ```bash -base=master # Для проекта с main: base=main. -git fetch origin +git fetch origin && +git remote set-head origin --auto ``` Затем используй **один** согласованный способ — merge: ```bash -git merge "origin/$base" +git merge origin/HEAD ``` Или rebase: ```bash -git rebase "origin/$base" +git rebase origin/HEAD ``` Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index b6f455e..aa9c0ab 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 13:47:59 (1789220879) +completed: 2026-09-12 14:55:36 (1789224936) cancelled: value: V2 complexity: C2 @@ -60,6 +60,7 @@ status: done - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. - [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками без отдельной инструкции по их заполнению. +- [x] В `branches.md` определять основную ветку через актуальный `origin/HEAD`, без ручной подстановки `master`/`main`. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -178,6 +179,12 @@ git diff --check - По замечанию пользователя из обоих шаблонов удалена инструкция о замене подсказок. В плане срочного исправления поле заменено на «Тип выпуска: `hotfix`»; вид выпуска больше не обозначается уровнем повышения версии. - Сравнение с `c8953a0` подтвердило отсутствие других изменений шаблонов. Все 50 изменяемых полей и оба заголовка сохранены; установка и повторная установка 12 документов, Composer, ссылки, задача и форматирование проверены успешно. +### Определение основной ветки + +- В `branches.md` основная ветка обозначена как ветка по умолчанию. Команды обновляют `origin/HEAD`; для переключения получают имя локальной ветки, для слияния и переноса используют ссылку напрямую. Убрана ручная замена `master`/`main`. +- Команды документации проверены в 27 изолированных сценариях: `master`, `main` и имя с вложенным путём; актуальная, отсутствующая и устаревшая ссылка; создание задачи, слияние и перенос. Ещё три проверки подтверждают остановку создания задачи при недоступном репозитории, неопределённой основной ветке и расхождении локальной базы. +- Composer, задача, ссылки и форматирование проверены; установка и повторная установка 12 документов совпадают с исходниками. Правила срочного выпуска и теги не менялись. + ## 7. Риски и зависимости (Risks and Dependencies) - Проекты-потребители получат исправления только после выпуска версии пакета и повторной установки документов. - CI самого пакета (`.github/workflows/ci.yml`) пока запускается только для PR в `master`/`main`. Перед реальным срочным выпуском пакета нужно отдельно согласовать добавление `release/*` в целевые ветки CI; конфигурация не входит в текущие правки документации. В TasK CI уже обрабатывает PR без ограничения целевой ветки. @@ -215,3 +222,4 @@ git diff --check | 2026-09-12 | Технический писатель (pi) | Пустые поля обоих шаблонов дополнены предметными подсказками; добавлена инструкция по их замене данными выпуска | | 2026-09-12 | Технический писатель (pi) | Исправлена неполнота предыдущей правки: все изменяемые поля, включая тег, ветки и заголовки, приведены к единому формату подсказок | | 2026-09-12 | Технический писатель (pi) | Удалена избыточная инструкция по заполнению; в плане срочного исправления указан тип выпуска hotfix вместо уровня повышения версии | +| 2026-09-12 | Технический писатель (pi) | В branches.md ручная подстановка master/main заменена определением основной ветки через origin/HEAD; команды проверены в изолированных репозиториях | From d7edffcb3d8bc8c42911c82c8875c804ff38d8a9 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sat, 12 Sep 2026 22:54:13 +0700 Subject: [PATCH 21/40] =?UTF-8?q?docs(release):=20retain=20each=20release?= =?UTF-8?q?=20branch=20/=20=D1=81=D0=BE=D1=85=D1=80=D0=B0=D0=BD=D1=8F?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B2=D0=B5=D1=82=D0=BA=D1=83=20=D0=BA=D0=B0?= =?UTF-8?q?=D0=B6=D0=B4=D0=BE=D0=B3=D0=BE=20=D0=B2=D1=8B=D0=BF=D1=83=D1=81?= =?UTF-8?q?=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 28 ++++---- docs/git-workflow/deploy.md | 2 +- docs/git-workflow/pull-request.md | 21 +++--- docs/git-workflow/release-checklists.md | 22 ++++--- docs/git-workflow/release.md | 65 ++++++++++--------- .../templates/hotfix-release-plan.template.md | 6 +- .../templates/release-plan.template.md | 8 +-- ...K-docs-align-workflow-instructions.todo.md | 30 ++++++--- 8 files changed, 101 insertions(+), 81 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 02ba01c..2ff6427 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -17,15 +17,15 @@ package: prikotov/git-workflow - Основная ветка — ветка по умолчанию репозитория и источник обычных релизов; на неё указывает `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` выпущенной линии для срочного исправления. +- Одновременно готовь один обычный релиз; срочное исправление может готовиться параллельно. Сохраняй ветки всех выпусков. ## Общие правила - Вноси изменения в основную ветку только через PR. -- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй `release/x.y` выпущенной линии только через PR из `hotfix/*`. +- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй его `release/x.y.z` только через PR из `hotfix/*`. - Запрещён деплой в production из текущего состояния ветки. - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения. - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. @@ -35,12 +35,12 @@ package: prikotov/git-workflow ## Именование - `task/` — английский, `kebab-case`, кратко по смыслу. -- `release/x.y` — release line по `major.minor`. +- `release/x.y.z` — полный номер выпуска по `major.minor.patch`. - `hotfix/x.y.z-` — patch version плюс короткое описание. Примеры: - `task/docs-release-workflow` -- `release/0.9` +- `release/0.9.3` - `hotfix/0.9.3-login-timeout` ## Откуда создавать ветки @@ -65,27 +65,27 @@ git switch -c task/ Правила для ветки обычного релиза: - коммить исправления, версии и релизные документы в этой ветке; - направляй PR из неё в основную ветку; слей PR до публикации тега; -- PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y`; -- продолжай начатый выпуск в существующей ветке; перед новым обычным выпуском заверши предыдущий, не перезаписывай ветку принудительно. +- PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y.z`; +- продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую. -Для срочного исправления используй `release/x.y` выпущенной линии. Удалённую ветку создай заново от рабочего тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Не подменяй её веткой следующего релиза. +Для срочного исправления создай `release/x.y.z` нового выпуска от текущего рабочего тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Например: от `v1.2.0` — новую `release/1.2.1`, не меняя `release/1.2.0`. ### Hotfix branch -Создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.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 ``` -Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y` выпущенной линии до создания нового тега. После выпуска верни патч-релиз отдельным PR из `release/x.y` в основную ветку по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега. После выпуска верни исправление отдельным PR из этой релизной ветки в основную по [сценарию срочного исправления](release.md#hotfix-и-patch-release). ## Синхронизация - Синхронизируй `task/*` и ветку обычного релиза с основной веткой до окончательного одобрения PR. -- Синхронизируй `hotfix/*` с целевой `release/x.y` выпущенной линии до окончательного одобрения PR. -- До срочного выпуска не подтягивай основную ветку в `hotfix/*` или `release/x.y` исправляемой линии. Адаптацию к основной ветке выполняй после выпуска при подготовке PR возврата. +- Синхронизируй `hotfix/*` с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. +- До срочного выпуска не подтягивай основную ветку в `hotfix/*` или его `release/x.y.z`. Адаптацию к основной ветке выполняй после выпуска в этой релизной ветке при подготовке PR возврата. - Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. Для обычной задачи или обычного релиза получи актуальное состояние основной ветки: @@ -112,5 +112,5 @@ git rebase origin/HEAD ## Завершение - Удали `task/*` локально и в `origin` после слияния PR. -- Сохраняй `release/*` до завершения выпуска и закрытия линии. Перед удалением проверь, что изменения слиты в основную ветку. Сохрани тег выпущенной версии; отменённого кандидата не тегируй. +- Сохраняй все `release/*` локально и в `origin`, а также теги выпусков. Не удаляй релизную ветку при слиянии PR и не переиспользуй для другой версии. Отменённого кандидата не тегируй. - Удали `hotfix/*` после выпуска и слияния исправления в основную ветку. diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index ff631a4..3f4bcc6 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -16,7 +16,7 @@ package: prikotov/git-workflow ## Правила - Production deploy выполняется только по **конкретному release tag** `vX.Y.Z`. -- Деплой из `master` или `release/x.y` branch head запрещён. +- Выкладка из вершины ветки запрещена. - Если релиз включает миграции — деплой должен учитывать порядок действий и риски. - Production incidents после деплоя закрываются через hotfix или patch release, а не через rollback. diff --git a/docs/git-workflow/pull-request.md b/docs/git-workflow/pull-request.md index c325eea..c1a84e9 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -16,7 +16,7 @@ package: prikotov/git-workflow ## Правила -- Вноси изменения в `master`/`main` только через PR. Коммить в рабочих ветках `task/*`, `release/*` и `hotfix/*` только по запросу пользователя. +- Вноси изменения в основную ветку только через PR. Коммить в рабочих ветках `task/*`, `release/*` и `hotfix/*` только по запросу пользователя. - Одна обычная задача — один PR, либо одна подзадача, если задача большая. - Не смешивай изменения из разных задач. - Держи PR минимальным по объёму. @@ -38,12 +38,12 @@ package: prikotov/git-workflow ## Выбор base branch -- Основная ветка проекта — `master` или `main`. Далее она обозначается как `master`. +- На основную ветку указывает `origin/HEAD` по [правилам веток](branches.md#целевая-модель). - Обычная задача: `task/` от актуальной основной ветки → PR в основную ветку. -- Обычный релиз: `release/x.y` от актуальной основной ветки → PR в основную ветку до публикации тега. -- Срочное исправление: `hotfix/x.y.z-` от рабочего тега → PR в `release/x.y` выпущенной линии до публикации нового тега. Создание удалённой ветки от тега описано в [сценарии срочного исправления](release.md#hotfix-и-patch-release). -- Возврат срочного исправления: отдельный PR из `release/x.y` выпущенной линии в основную ветку после выпуска. -- До срочного выпуска не синхронизируй `hotfix/*` и целевую `release/x.y` с основной веткой. Если для возврата нужны доработки, выполни их после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. +- Обычный релиз: отдельная `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` с основной веткой. Если для возврата нужны доработки, выполни их в релизной ветке после выпуска с повторными проверками и одобрением; опубликованный тег не меняется. ## Обязательные проверки @@ -68,7 +68,7 @@ package: prikotov/git-workflow - Заголовок PR: английский, кратко отражает суть. - Для release и hotfix PR явно укажи: - - релизную ветку `release/x.y` либо ветку срочного исправления `hotfix/*`; + - релизную ветку `release/x.y.z` либо ветку срочного исправления `hotfix/*`; - production tag, который исправляем или выпускаем; - порядок выпуска и включения изменений в основную ветку; - какие изменения сознательно **не** входят в этот релиз. @@ -115,11 +115,12 @@ package: prikotov/git-workflow - После approval пользователя заверши PR через GitHub (`gh pr merge`). - Запрещено выполнять локальный merge PR-ветки в целевую ветку. - Слей PR подготовки обычного релиза или срочного исправления до публикации тега. -- PR возврата срочного исправления из `release/x.y` в основную ветку слей после выпуска. +- PR возврата срочного исправления из `release/x.y.z` в основную ветку слей после выпуска. Не удаляй исходную релизную ветку при слиянии. ## После merge -- После merge PR в `master` переключись на `master` и обнови его: `git pull --ff-only origin master`. -- Удали `task/*` локально и в `origin`. Для `release/*` дождись завершения выпуска и закрытия линии; для `hotfix/*` — выпуска и включения исправления в основную ветку. +- После 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 aae9ac1..de59a0e 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -14,29 +14,31 @@ package: prikotov/git-workflow - Следующая версия выбрана по [правилам SemVer](release.md#semver-и-линии-релиза). - Несовместимые изменения в `0.x` повышают `minor`; начиная с `1.0.0` — `major`. - Несовместимость явно отмечена в `CHANGELOG.md` и плане релиза независимо от номера версии. -- Рабочая ветка `release/x.y` создана от актуальной основной ветки по [процессу релиза](release.md#1-финализация-в-релизной-ветке). +- Для выбранной полной версии создана отдельная `release/x.y.z` от актуальной основной ветки по [процессу релиза](release.md#1-финализация-в-релизной-ветке). Ветка другого выпуска не переиспользована. - Документы обновлены под состав релиза и содержат действия до и после выпуска. Существующий `release-plan.md` не перезаписан шаблоном. -- Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y` вручную, без автоматического тега. -- PR (запрос на слияние) открыт из `release/x.y` в основную ветку; синхронизация завершена до окончательного одобрения. +- Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y.z` вручную, без автоматического тега. +- PR (запрос на слияние) открыт из `release/x.y.z` в основную ветку; синхронизация завершена до окончательного одобрения. - Все изменения, включая данные задачи, закоммичены до окончательных проверок и одобрения PR. - Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. - Автоматические проверки PR (CI) успешны. Пользователь одобрил проверенный PR и подтвердил слияние; PR слит через GitHub. -- Коммит слияния входит в историю основной ветки и совпадает по содержимому с одобренным коммитом `release/x.y`; оба SHA зафиксированы: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). +- Коммит слияния входит в историю основной ветки и совпадает по содержимому с одобренным коммитом `release/x.y.z`; оба SHA зафиксированы: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). +- Релизная ветка и тег сохраняются после выпуска. ## Чеклист срочного исправления - Определён текущий тег релиза на production `vX.Y.Z`. -- Рабочая ветка срочного исправления `hotfix/x.y.z-` создана от тега рабочей среды, а не от ветки `master`. +- Рабочая ветка `hotfix/x.y.z-` и целевая `release/x.y.z` нового выпуска созданы от текущего рабочего тега, не от основной или сохранённой релизной ветки. - Объём срочного исправления минимален и не тянет несвязанные изменения. -- Цель PR — `release/x.y` выпущенной линии. Если ветка была удалена, она создана заново от рабочего тега; ветка следующего релиза не затронута. -- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y` завершена до одобрения. +- Имя ветки и тег соответствуют новой полной версии. Ветки предыдущих и параллельно готовящихся выпусков не переиспользованы и не перезаписаны. +- Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y.z` завершена до одобрения. - Перед срочным выпуском выполнен `make check` по правилам проекта; проверки и CI успешны. - Если пользователь явно запросил сквозные тесты, они выполнены успешно; без запроса не запускались. -- Проверенный PR из `hotfix/*` в `release/x.y` одобрен и слит через GitHub с подтверждением пользователя. -- Коммит слияния входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. +- Проверенный PR из `hotfix/*` в `release/x.y.z` нового выпуска одобрен и слит через GitHub с подтверждением пользователя. +- Коммит слияния входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. - Выпуск разрешён. Новый тег отмечает проверенный результат слияния по [сценарию срочного исправления](release.md#hotfix-и-patch-release). -- После выпуска запланирован отдельный PR возврата из `release/x.y` выпущенной линии в основную ветку; адаптация и конфликты не меняют опубликованный тег. +- После выпуска запланирован отдельный PR возврата из этой `release/x.y.z` в основную ветку, без временной ветки. Адаптация и конфликты не меняют опубликованный тег. +- После возврата исправления `hotfix/*` удаляется, релизная ветка и тег сохраняются. ## Чеклист выкладки diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 72c8737..63de022 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -4,16 +4,15 @@ package: prikotov/git-workflow # Релизы и CHANGELOG -Основная ветка проекта — `master` или `main`. В примерах используется `master`; для `main` замените имя в командах. - ## Модель релизов -- Финализируйте обычный релиз в `release/x.y` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. -- Для обычного релиза направляйте запрос на слияние (Pull Request, PR) из `release/x.y` в основную ветку. +- Для каждого выпуска создавайте отдельную `release/x.y.z`, включая каждый патч. Сохраняйте все релизные ветки и теги, не переиспользуйте ветку для другой версии. +- Финализируйте обычный релиз в `release/x.y.z` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. +- Для обычного релиза направляйте запрос на слияние (Pull Request, PR) из `release/x.y.z` в основную ветку. - После проверок и одобрения слейте PR обычного релиза. Поставьте тег на проверенный коммит слияния. -- Изменяйте `master`/`main` только через PR. Коммитьте в рабочих ветках только по запросу пользователя. +- Изменяйте основную ветку только через PR. Коммитьте в рабочих ветках только по запросу пользователя. - Разворачивайте рабочую среду (production) по неизменяемому тегу `vX.Y.Z`, не по последнему коммиту ветки. -- Поддерживайте одну ветку обычного релиза. Для срочного исправления допускается отдельная `release/x.y` выпущенной линии. +- Одновременно готовьте один обычный релиз; срочное исправление может готовиться параллельно. Сохранённые ветки завершённых выпусков этому не мешают. - Для срочного исправления от рабочего тега следуйте [отдельному сценарию](#hotfix-и-patch-release). ## SemVer и линии релиза @@ -97,26 +96,29 @@ git diff ### 1. Финализация в релизной ветке -Выберите версию по SemVer и создайте `release/x.y` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке. Перед новым обычным выпуском завершите предыдущий по [правилам веток](branches.md#завершение); имя должно быть свободно локально и в `origin`, принудительная перезапись запрещена. +Выберите версию по SemVer и создайте `release/x.y.z` от актуальной основной ветки. Если подготовка этого выпуска уже идёт, продолжайте в существующей ветке, проверив её базу и состав. Для нового выпуска имя ветки и тег должны быть свободны локально и в `origin`; при конфликте остановитесь, не перезаписывайте их. -Замените `x.y` номером линии: +Замените `x.y.z` полной версией выпуска: ```bash -git switch master && - git pull --ff-only origin master && - git switch -c release/x.y && - git push -u origin release/x.y +git fetch origin && + git remote set-head origin --auto && + base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && + 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 ``` -1. В `release/x.y` внесите исправления, обновите `CHANGELOG.md`, файлы версий и релизные документы. +1. В `release/x.y.z` внесите исправления, обновите `CHANGELOG.md`, файлы версий и релизные документы. 2. Проверьте diff и создайте коммиты вручную по [commits.md](commits.md). -3. Откройте PR **из `release/x.y` в основную ветку** по [правилам PR](pull-request.md). +3. Откройте PR **из `release/x.y.z` в основную ветку** по [правилам PR](pull-request.md). 4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните `make check` и обязательный предрелизный запуск `make tests-e2e`; дождитесь успеха. Проектные исключения для `make check` не отменяют сквозные тесты. -5. Зафиксируйте SHA проверенного состояния `release/x.y`. Дождитесь успешных автоматических проверок PR (CI), одобрения и подтверждения слияния пользователем. Выполните слияние через GitHub. Доработки требуют [повторного одобрения](pull-request.md#подготовка-pr). +5. Зафиксируйте SHA проверенного состояния `release/x.y.z`. Дождитесь успешных автоматических проверок PR (CI), одобрения и подтверждения слияния пользователем. Выполните слияние через GitHub. Доработки требуют [повторного одобрения](pull-request.md#подготовка-pr). ### 2. Проверка коммита выпуска -Получите SHA коммита слияния PR из GitHub. Сравните его содержимое с одобренным коммитом `release/x.y`. Не подставляйте текущий `HEAD` основной ветки. +Получите SHA коммита слияния PR из GitHub. Сравните его содержимое с одобренным коммитом `release/x.y.z`. Не подставляйте текущий `HEAD` основной ветки. Подставьте полные SHA коммита слияния и одобренного коммита релизной ветки: @@ -124,7 +126,8 @@ git switch master && release_commit=VERIFIED_MERGE_SHA release_head=APPROVED_RELEASE_SHA git fetch origin && - git merge-base --is-ancestor "$release_commit" origin/master && + git remote set-head origin --auto && + git merge-base --is-ancestor "$release_commit" origin/HEAD && git diff --exit-code "$release_head" "$release_commit" -- ``` @@ -156,27 +159,29 @@ gh release create vX.Y.Z --verify-tag --notes-file tmp/release-vX.Y.Z.md ## Hotfix и patch release -Определите текущий тег рабочей среды `vX.Y.Z`. Цель PR исправления — `release/x.y` этой выпущенной линии. Если ветка удалена локально и в `origin`, создайте её от рабочего тега: +Определите текущий тег рабочей среды `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 git fetch origin --tags --prune && - git switch -c release/x.y vX.Y.Z && - git push -u origin release/x.y + git switch -c release/x.y.z vX.Y.Z && + git push -u origin release/x.y.z ``` -Если ветка существует, проверьте её базу и состав изменений. Не используйте ветку следующего релиза и не перезаписывайте её. При конфликте имени или несогласованных изменениях остановитесь и согласуйте состав и выбор ветки. +Если подготовка этого выпуска уже идёт, продолжайте в его ветке, проверив базу и состав. При занятой версии или несогласованных изменениях остановитесь и уточните дальнейшие действия. Не переиспользуйте и не перезаписывайте ветки других выпусков. -Ветку следующего обычного релиза сохраняйте: она может существовать одновременно с веткой срочного выпуска. До выпуска не подтягивайте `master`/`main` в `hotfix/*` и `release/x.y` исправляемой линии. +До выпуска не подтягивайте основную ветку в `hotfix/*` и целевую `release/x.y.z`. При срочном исправлении запускайте сквозные тесты только по явному запросу пользователя. Если затронут критический пользовательский сценарий, предложите точечный запуск вместо полного `make tests-e2e`. -1. Создайте `hotfix/x.y.z-` от рабочего тега по [правилам веток](branches.md#hotfix-branch). -2. Исправьте проблему и подготовьте файлы патч-релиза `vX.Y.(Z+1)` в `hotfix/*`. Убедитесь, что CI проекта запускается для целевой `release/x.y`. Откройте PR **из `hotfix/*` в `release/x.y` выпущенной линии**. -3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y`. Завершите все правки, выполните `make check` по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. -4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y` и совпадает по содержимому с одобренным коммитом `hotfix/*`: +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`. Завершите все правки, выполните `make check` по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. +4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`: ```bash -release_branch=release/x.y +release_branch=release/x.y.z release_commit=VERIFIED_HOTFIX_MERGE_SHA hotfix_head=APPROVED_HOTFIX_SHA git fetch origin && @@ -184,12 +189,12 @@ git fetch origin && git diff --exit-code "$hotfix_head" "$release_commit" -- ``` -При ошибке остановите выпуск. Доработки проведите через новый PR из `hotfix/*` в `release/x.y` с повторными проверками и одобрением. Изменение только SHA при совпадающем содержимом не требует полного повторного прогона или отдельного CI. +При ошибке остановите выпуск. Доработки проведите через новый PR из `hotfix/*` в ту же `release/x.y.z` с повторными проверками и одобрением. Изменение только SHA при совпадающем содержимом не требует полного повторного прогона или отдельного CI. 5. После разрешения на выпуск [опубликуйте новый тег](#3-создание-и-публикация-тега) **на проверенном результате слияния**. Выпустите патч по этому тегу. -6. Сразу после выпуска откройте отдельный PR **из `release/x.y` выпущенной линии в `master`/`main`**. Выполните проверки, получите одобрение и подтверждение слияния. Если нужны адаптация или разрешение конфликтов, внесите их в эту `release/x.y` после выпуска и повторите проверки и одобрение. Не меняйте опубликованный тег. +6. Сразу после выпуска откройте отдельный PR **из этой `release/x.y.z` в основную ветку**. Выполните проверки, получите одобрение и подтверждение слияния. Если нужны адаптация или разрешение конфликтов, внесите их в эту релизную ветку после выпуска и повторите проверки и одобрение. Временная ветка для возврата не нужна. Не меняйте опубликованный тег. -Исправление попадёт в ветку следующего обычного релиза при её синхронизации с основной веткой. После выпуска и возврата исправления удалите рабочие ветки по [правилам завершения](branches.md#завершение). +Исправление попадёт в ветку следующего обычного релиза при её синхронизации с основной веткой. После выпуска и возврата удалите `hotfix/*`, сохраните `release/x.y.z` и тег. Для следующего срочного исправления создайте новые ветки от текущего рабочего тега, не от изменённой вершины сохранённой ветки. ## Recovery Policy diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 0566432..fbf3d01 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -9,7 +9,7 @@ - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] - База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] - Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] -- PR срочного исправления в `release/x.y` (слить до выпуска): [ссылка на PR] +- PR срочного исправления в `release/x.y.z` (слить до выпуска): [ссылка на PR в ветку нового выпуска] - PR включения срочного исправления в основную ветку (после выпуска): [ссылка на PR после его создания] - Ответственный: [имя или ссылка на профиль] - Плановая дата deploy: [дата, время и часовой пояс] @@ -37,7 +37,7 @@ - Выполнить `make check` по правилам проекта; дождаться успешного результата - Запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок -- До публикации тега проверить, что PR из `hotfix/*` слит в `release/x.y` выпущенной линии +- До публикации тега проверить, что PR из `hotfix/*` слит в `release/x.y.z` нового выпуска - Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения @@ -46,7 +46,7 @@ ## План проверок после выкладки -- Проверить, что исправление включено в `master` / `main` через PR из `release/x.y` выпущенной линии +- Проверить, что исправление включено в основную ветку через PR из этой `release/x.y.z` - Основные пользовательские сценарии и ожидаемые результаты: [шаги проверки и признаки успеха] - Проверяемые логи и признаки ошибок: [источники логов и сообщения, требующие реакции] - Ожидаемое состояние очередей и обработчиков: [проверяемые показатели и допустимые значения] diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 3877c20..5c47fd4 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -7,8 +7,8 @@ - Тег релиза: [тег в формате `vX.Y.Z`] - Тип повышения версии: [`major`, `minor` или `patch`] - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] -- База рабочей ветки: [актуальная основная ветка: `master` или `main`] -- Рабочая ветка: [ветка в формате `release/x.y`] +- База рабочей ветки: [актуальная основная ветка по `origin/HEAD`] +- Рабочая ветка: [ветка в формате `release/x.y.z`] - PR подготовки релиза (слить до выпуска): [ссылка на PR] - Ответственный: [имя или ссылка на профиль] - Плановая дата deploy: [дата, время и часовой пояс] @@ -36,8 +36,8 @@ - Выполнить `make check` по правилам проекта; дождаться успешного результата - Обязательно выполнить `make tests-e2e`; дождаться успешного результата -- До публикации тега проверить, что PR из `release/x.y` слит в основную ветку -- Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y` +- До публикации тега проверить, что PR из `release/x.y.z` слит в основную ветку +- Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y.z` - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения - Проверить готовность миграций, порядок их применения и риск окна несовместимости diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index aa9c0ab..821060e 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 14:55:36 (1789224936) +completed: 2026-09-12 15:51:10 (1789228270) cancelled: value: V2 complexity: C2 @@ -48,9 +48,10 @@ status: done ## 3. Требования, MoSCoW (Requirements) ### 🔴 Обязательно (Must Have) -- [x] Финализировать обычный релиз в `release/x.y` от актуальной основной ветки `master`/`main`; PR направлять из неё в основную ветку до выпуска. Срочное исправление от рабочего тега описывать отдельно. -- [x] Включать изменения в основную ветку только через PR; сохранить работу и коммиты в `release/*` обычного релиза без промежуточной `task/prepare-release-*`. Срочные исправления сливать через PR из `hotfix/*` в `release/x.y` выпущенной линии до нового тега. -- [x] Для срочного исправления создавать удалённую ветку выпущенной линии заново от рабочего тега; допускать её одновременно с веткой следующего обычного релиза. Возвращать выпущенный патч отдельным PR из `release/x.y` в основную ветку. +- [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] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. @@ -69,12 +70,12 @@ status: done 1. [x] Сверить документы пакета и реальные параметры упоминаемых инструментов. 2. [x] Точечно согласовать ветки, подготовку коммитов, проверки и релиз через PR. 3. [x] Проверить ссылки, выполнить `composer validate --strict` и проверку установки документации во временный каталог. -4. [x] Провести самопроверку и независимое ревью, устранить замечания. +4. [x] Провести личную вычитку без делегирования, устранить замечания. 5. [x] Создать PR с меткой `pi`, заполнить ссылку, дождаться CI и подготовить задачу к приёмке. ## 5. Критерии приёмки (Definition of Done) - [x] Все обязательные требования выполнены; инструкции не требуют прямой записи в целевые ветки. -- [x] Проверки Composer и документации успешны; независимое ревью не содержит блокирующих замечаний. +- [x] Проверки Composer и документации успешны; личная вычитка не выявила блокирующих замечаний. - [x] PR открыт, задача связана с ним и готова к приёмке; версии и теги не выпускались. ## 6. Самопроверка (Verification) @@ -87,7 +88,7 @@ git diff --check ### Результат выполнения - Согласованы `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` от актуальной основной ветки; коммиты в ней разрешены, PR направляется в основную ветку до выпуска. Тег фиксирует проверенный результат слияния. Автокоммит, автотег и публикация всех тегов исключены. Срочное исправление проходит PR из `hotfix/*` в ветку выпущенной линии до нового тега, затем возвращается отдельным PR из этой ветки в основную. +- Каждый выпуск получает отдельную сохраняемую `release/x.y.z` и неизменяемый тег. Документы накапливаются в обычных задачах; обычный релиз финализируется в своей ветке от актуальной основной, затем PR сливается в основную до тега. Для срочного исправления обе новые ветки создаются от рабочего тега: PR `hotfix/*` → новая `release/x.y.z` → тег и выпуск → PR из неё в основную. Автокоммит, автотег и публикация всех тегов исключены. - Сохранены SemVer и production по фиксированному тегу. Сообщения коммитов — вручную, английский / русский; исключения проверок — только по явной политике потребителя. Механика задач оставлена источнику `todo-md`; служебные изменения не обходят окончательное одобрение. - Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к `make check` и CI сохранены. - Параметры `conventional-changelog` сверены read-only с README и `src/Changelog.php` установленного инструмента; `gh release create --help` подтверждает `--verify-tag`. Фактические релизные команды не запускались. @@ -103,7 +104,7 @@ git diff --check ### Доработка после замечаний пользователя -Ниже сохранена история промежуточных редакций. Порядок срочного исправления в них был изменён ошибочно; действующее решение приведено в разделе «Восстановление исходного маршрута срочного исправления». +Ниже сохранена история промежуточных редакций и ошибок агента. Действующий порядок приведён в разделе «Отдельная ветка каждого выпуска»; прежние правила общей `release/x.y` и её восстановления заменены. - Задача возвращена в `review` перед исправлениями. Во взаимосвязанных документах явно различены имена рабочих веток, пути файлов и идентификаторы коммитов. - Сохранён обязательный предрелизный запуск `make tests-e2e`. Убрано добавленное требование полного повторного прогона и отдельного CI только из-за нового идентификатора коммита после слияния. Непроверенные изменения проверяются по правилам проекта. @@ -185,10 +186,20 @@ git diff --check - Команды документации проверены в 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 без ограничения целевой ветки. -- Изменяется предписанный релизный процесс; пользователь подтвердил подготовку релиза через PR без разрешения прямых коммитов в целевые ветки. +- Изменяется предписанный релизный процесс; реальные слияния, теги и выпуски не разрешены. ## 8. Источники (Sources) - [Ветки](../../docs/git-workflow/branches.md). @@ -223,3 +234,4 @@ git diff --check | 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-модели | From 5ea742b866ebfa6b6b70202d5535f727e00eed40 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 08:50:54 +0700 Subject: [PATCH 22/40] =?UTF-8?q?docs(hotfix):=20describe=20release=20reas?= =?UTF-8?q?on=20/=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D1=82=D1=8C=20=D0=BF?= =?UTF-8?q?=D1=80=D0=B8=D1=87=D0=B8=D0=BD=D1=83=20=D0=B8=D1=81=D0=BF=D1=80?= =?UTF-8?q?=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/hotfix-release-plan.template.md | 2 +- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index fbf3d01..79ef10d 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -6,7 +6,7 @@ - Тег релиза: [тег в формате `vX.Y.Z`] - Тип выпуска: `hotfix` -- Обоснование выбранной версии: [причина повышения версии с учётом совместимости] +- Причина срочного исправления: [описание ошибки] - База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] - Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] - PR срочного исправления в `release/x.y.z` (слить до выпуска): [ссылка на PR в ветку нового выпуска] diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 821060e..cee424b 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-12 15:51:10 (1789228270) +completed: 2026-09-13 01:50:54 (1789264254) cancelled: value: V2 complexity: C2 @@ -235,3 +235,4 @@ git diff --check | 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-12 | Технический писатель (pi) | В срочном плане обоснование версии заменено на причину исправления с описанием ошибки: hotfix сохраняет совместимость. Проверены точечность правки, Composer, задача, ссылки и установка документов | From c7ac46908cac8519b93df0d380ab4a8e2e78938a Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 08:51:32 +0700 Subject: [PATCH 23/40] =?UTF-8?q?docs(task):=20correct=20revision=20date?= =?UTF-8?q?=20/=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D0=B4=D0=B0=D1=82=D1=83=20=D1=83=D1=82=D0=BE=D1=87=D0=BD?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- todo/done/TASK-docs-align-workflow-instructions.todo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index cee424b..900d4ee 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -235,4 +235,4 @@ git diff --check | 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-12 | Технический писатель (pi) | В срочном плане обоснование версии заменено на причину исправления с описанием ошибки: hotfix сохраняет совместимость. Проверены точечность правки, Composer, задача, ссылки и установка документов | +| 2026-09-13 | Технический писатель (pi) | В срочном плане обоснование версии заменено на причину исправления с описанием ошибки: hotfix сохраняет совместимость. Проверены точечность правки, Composer, задача, ссылки и установка документов | From 4e7cccdf48a9d7413cbebc6aec32242d09a45558 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 09:00:18 +0700 Subject: [PATCH 24/40] =?UTF-8?q?docs(hotfix):=20remove=20redundant=20fiel?= =?UTF-8?q?ds=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=BB=D0=B8?= =?UTF-8?q?=D1=88=D0=BD=D0=B8=D0=B5=20=D0=BF=D0=BE=D0=BB=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/hotfix-release-plan.template.md | 2 -- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 79ef10d..2bf56ad 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -12,13 +12,11 @@ - PR срочного исправления в `release/x.y.z` (слить до выпуска): [ссылка на PR в ветку нового выпуска] - PR включения срочного исправления в основную ветку (после выпуска): [ссылка на PR после его создания] - Ответственный: [имя или ссылка на профиль] -- Плановая дата deploy: [дата, время и часовой пояс] ## Состав - Включённые PR: [ссылки на PR] - Включённые задачи: [ссылки на задачи] -- Вне состава релиза: [изменения, которые не войдут в выпуск] ## Риски diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 900d4ee..442dff8 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 01:50:54 (1789264254) +completed: 2026-09-13 02:00:18 (1789264818) cancelled: value: V2 complexity: C2 @@ -236,3 +236,4 @@ git diff --check | 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, задача, ссылки и установка документов | From 8e23b5e19d6273174e1b16209c217e271ce63c35 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 09:32:35 +0700 Subject: [PATCH 25/40] =?UTF-8?q?docs(glossary):=20define=20workflow=20ter?= =?UTF-8?q?ms=20/=20=D0=BE=D0=BF=D1=80=D0=B5=D0=B4=D0=B5=D0=BB=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20=D1=82=D0=B5=D1=80=D0=BC=D0=B8=D0=BD=D1=8B=20=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D1=86=D0=B5=D1=81=D1=81=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + README.md | 1 + docs/git-workflow/deploy.md | 2 +- docs/git-workflow/glossary.md | 93 +++++++++++++++++++ docs/git-workflow/index.md | 1 + docs/git-workflow/release.md | 2 +- ...K-docs-align-workflow-instructions.todo.md | 6 +- 7 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 docs/git-workflow/glossary.md diff --git a/AGENTS.md b/AGENTS.md index eae7b65..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 и требования 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/deploy.md b/docs/git-workflow/deploy.md index 3f4bcc6..f2f7cbd 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)](glossary.md#deployment)** — установка выбранной версии в рабочую среду с необходимыми действиями: обновление кода, установка зависимостей, миграции, прогрев кэша, перезапуск или перезагрузка сервисов. ## Границы ответственности 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/release.md b/docs/git-workflow/release.md index 63de022..40c65be 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -6,7 +6,7 @@ package: prikotov/git-workflow ## Модель релизов -- Для каждого выпуска создавайте отдельную `release/x.y.z`, включая каждый патч. Сохраняйте все релизные ветки и теги, не переиспользуйте ветку для другой версии. +- Для каждого [выпуска](glossary.md#release-publishing) создавайте отдельную `release/x.y.z`, включая каждый патч. Сохраняйте все релизные ветки и теги, не переиспользуйте ветку для другой версии. - Финализируйте обычный релиз в `release/x.y.z` от актуальной основной ветки. Коммитьте исправления и релизные файлы в неё. - Для обычного релиза направляйте запрос на слияние (Pull Request, PR) из `release/x.y.z` в основную ветку. - После проверок и одобрения слейте PR обычного релиза. Поставьте тег на проверенный коммит слияния. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 442dff8..f5272f3 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 02:00:18 (1789264818) +completed: 2026-09-13 02:32:07 (1789266727) cancelled: value: V2 complexity: C2 @@ -62,6 +62,7 @@ status: done - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. - [x] В обоих шаблонах оформить все изменяемые поля и заголовки единообразными подсказками без отдельной инструкции по их заполнению. - [x] В `branches.md` определять основную ветку через актуальный `origin/HEAD`, без ручной подстановки `master`/`main`. +- [x] Добавить словарь документации: русский термин, английский в скобках и пояснение через тире; обеспечить ссылки на отдельные определения. ### ⚫ Won't Have (Не будем делать) - Выпускать версии, создавать теги, выполнять слияние PR или обновлять зависимости TasK. - Массово переписывать документацию вне выявленных противоречий. @@ -87,7 +88,7 @@ git diff --check ### Результат выполнения -- Согласованы `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/`. +- Согласованы `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`; служебные изменения не обходят окончательное одобрение. - Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к `make check` и CI сохранены. @@ -237,3 +238,4 @@ git diff --check | 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 и задача | From 32be11fe0217d64660361959020577a8fcd20f04 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 09:51:54 +0700 Subject: [PATCH 26/40] =?UTF-8?q?docs(hotfix):=20clarify=20PR=20timing=20/?= =?UTF-8?q?=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8=D1=82=D1=8C=20=D0=BF?= =?UTF-8?q?=D0=BE=D1=80=D1=8F=D0=B4=D0=BE=D0=BA=20=D0=B4=D0=B5=D0=B9=D1=81?= =?UTF-8?q?=D1=82=D0=B2=D0=B8=D0=B9=20=D1=81=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/hotfix-release-plan.template.md | 6 +++--- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 2bf56ad..393a868 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -9,8 +9,8 @@ - Причина срочного исправления: [описание ошибки] - База рабочей ветки (тег текущей версии в рабочей среде): [тег исправляемой версии в формате `vX.Y.Z`] - Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] -- PR срочного исправления в `release/x.y.z` (слить до выпуска): [ссылка на PR в ветку нового выпуска] -- PR включения срочного исправления в основную ветку (после выпуска): [ссылка на PR после его создания] +- PR срочного исправления в `release/x.y.z` (слить до создания тега): [ссылка на PR в ветку нового выпуска] +- PR включения срочного исправления в основную ветку (открыть после публикации GitHub Release): [ссылка на PR после его создания] - Ответственный: [имя или ссылка на профиль] ## Состав @@ -35,7 +35,7 @@ - Выполнить `make check` по правилам проекта; дождаться успешного результата - Запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок -- До публикации тега проверить, что PR из `hotfix/*` слит в `release/x.y.z` нового выпуска +- До создания тега проверить, что PR из `hotfix/*` слит в `release/x.y.z` нового выпуска - Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index f5272f3..149ac18 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 02:32:07 (1789266727) +completed: 2026-09-13 02:51:54 (1789267914) cancelled: value: V2 complexity: C2 @@ -239,3 +239,4 @@ git diff --check | 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 документов | From 38b2a854617df6b08a711a20a41c7951442b5b05 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:00:41 +0700 Subject: [PATCH 27/40] =?UTF-8?q?docs(hotfix):=20simplify=20risk=20section?= =?UTF-8?q?=20/=20=D1=83=D0=BF=D1=80=D0=BE=D1=81=D1=82=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=20=D1=80=D0=B8=D1=81?= =?UTF-8?q?=D0=BA=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/hotfix-release-plan.template.md | 6 ++---- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 393a868..8e8bd4d 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -20,11 +20,9 @@ ## Риски -- Основные риски: [риски выпуска и меры их снижения] +- Основные риски: [риски исправления и выкладки, меры их снижения] - Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] - Порядок применения миграций: [команды и последовательность применения] -- Риск окна несовместимости: [несовместимые компоненты, длительность окна и меры защиты] -- Замечания по обратной совместимости: [затронутые контракты и необходимые действия] ## Порядок deploy @@ -39,7 +37,7 @@ - Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения -- Проверить готовность миграций, порядок их применения и риск окна несовместимости +- Проверить готовность миграций и безопасность порядка обновления кода и данных - Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] ## План проверок после выкладки diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 149ac18..d8be968 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 02:51:54 (1789267914) +completed: 2026-09-13 03:00:41 (1789268441) cancelled: value: V2 complexity: C2 @@ -240,3 +240,4 @@ git diff --check | 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 документов | From c2d89c55c07e2b7555f658c0c8d3c83f03586de4 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:07:08 +0700 Subject: [PATCH 28/40] =?UTF-8?q?docs(hotfix):=20clarify=20recovery=20and?= =?UTF-8?q?=20roles=20/=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D0=B4=D0=B5=D0=B9=D1=81=D1=82=D0=B2=D0=B8=D1=8F=20=D0=B8=20?= =?UTF-8?q?=D1=80=D0=BE=D0=BB=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/templates/hotfix-release-plan.template.md | 6 +++--- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 8e8bd4d..45e49f0 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -11,7 +11,7 @@ - Рабочая ветка: [ветка в формате `hotfix/x.y.z-`] - PR срочного исправления в `release/x.y.z` (слить до создания тега): [ссылка на PR в ветку нового выпуска] - PR включения срочного исправления в основную ветку (открыть после публикации GitHub Release): [ссылка на PR после его создания] -- Ответственный: [имя или ссылка на профиль] +- Ответственный: [имя или ссылка на профиль роли] ## Состав @@ -51,8 +51,8 @@ ## Действия при проблеме после релиза - Откат: не используется -- Стратегия исправления: [выбранная стратегия: `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 index d8be968..085b13b 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:00:41 (1789268441) +completed: 2026-09-13 03:07:08 (1789268828) cancelled: value: V2 complexity: C2 @@ -241,3 +241,4 @@ git diff --check | 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 документов | From cf50b2d1d6b2d9518d976a99b3191e17fb900bfd Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:16:28 +0700 Subject: [PATCH 29/40] =?UTF-8?q?docs(release):=20align=20plan=20templates?= =?UTF-8?q?=20/=20=D1=81=D0=BE=D0=B3=D0=BB=D0=B0=D1=81=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D1=82=D1=8C=20=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD=D1=8B=20?= =?UTF-8?q?=D0=BF=D0=BB=D0=B0=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../templates/release-plan.template.md | 20 +++++++++---------- ...K-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index 5c47fd4..cc3317e 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -9,23 +9,21 @@ - Обоснование выбранной версии: [причина повышения версии с учётом совместимости] - База рабочей ветки: [актуальная основная ветка по `origin/HEAD`] - Рабочая ветка: [ветка в формате `release/x.y.z`] -- PR подготовки релиза (слить до выпуска): [ссылка на PR] -- Ответственный: [имя или ссылка на профиль] -- Плановая дата deploy: [дата, время и часовой пояс] +- PR подготовки релиза в основную ветку (слить до создания тега): [ссылка на PR] +- Ответственный: [имя или ссылка на профиль роли] +- Плановая дата выкладки: [дата, время и часовой пояс] ## Состав - Включённые PR: [ссылки на PR] - Включённые задачи: [ссылки на задачи] -- Вне состава релиза: [изменения, которые не войдут в выпуск] ## Риски -- Основные риски: [риски выпуска и меры их снижения] +- Основные риски: [риски изменений и выкладки, меры их снижения] - Наличие миграций данных: [перечень миграций или подтверждение их отсутствия] - Порядок применения миграций: [команды и последовательность применения] -- Риск окна несовместимости: [несовместимые компоненты, длительность окна и меры защиты] -- Замечания по обратной совместимости: [затронутые контракты и необходимые действия] +- Несовместимые изменения: [перечень изменений и действия для перехода либо подтверждение сохранения совместимости] ## Порядок deploy @@ -36,11 +34,11 @@ - Выполнить `make check` по правилам проекта; дождаться успешного результата - Обязательно выполнить `make tests-e2e`; дождаться успешного результата -- До публикации тега проверить, что PR из `release/x.y.z` слит в основную ветку +- До создания тега проверить, что PR из `release/x.y.z` слит в основную ветку - Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y.z` - Убедиться, что согласованный тег опубликован в `origin` - Проверить необходимые изменения переменных окружения -- Проверить готовность миграций, порядок их применения и риск окна несовместимости +- Проверить готовность миграций и безопасность порядка обновления кода и данных - Команды проверки работоспособности (health-check) и ожидаемые результаты: [команды, ожидаемые ответы и коды завершения] ## План проверок после выкладки @@ -53,8 +51,8 @@ ## Действия при проблеме после релиза - Откат: не используется -- Стратегия исправления: [выбранная стратегия: `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 index 085b13b..44a5785 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:07:08 (1789268828) +completed: 2026-09-13 03:16:21 (1789269381) cancelled: value: V2 complexity: C2 @@ -242,3 +242,4 @@ git diff --check | 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 документов | From b598dc9614c202ac769b4af7e37f20aaba5f8f5a Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:23:04 +0700 Subject: [PATCH 30/40] =?UTF-8?q?docs(branches):=20restore=20release=20exa?= =?UTF-8?q?mples=20/=20=D0=B2=D0=B5=D1=80=D0=BD=D1=83=D1=82=D1=8C=20=D0=BF?= =?UTF-8?q?=D1=80=D0=B8=D0=BC=D0=B5=D1=80=D1=8B=20=D1=80=D0=B5=D0=BB=D0=B8?= =?UTF-8?q?=D0=B7=D0=BD=D1=8B=D1=85=20=D0=B2=D0=B5=D1=82=D0=BE=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 20 ++++++++++++++++++- ...K-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 2ff6427..d609c89 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -60,15 +60,33 @@ git switch -c task/ ### Release branch +Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска. + Для обычного релиза создай ветку от актуальной основной: [процесс релиза](release.md#1-финализация-в-релизной-ветке). +```bash +git fetch origin && + git remote set-head origin --auto && + base=$(git symbolic-ref --short refs/remotes/origin/HEAD) && + 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 до публикации тега; - PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y.z`; - продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую. -Для срочного исправления создай `release/x.y.z` нового выпуска от текущего рабочего тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Например: от `v1.2.0` — новую `release/1.2.1`, не меняя `release/1.2.0`. +Для срочного исправления создай `release/x.y.z` нового выпуска от текущего рабочего тега `vX.Y.Z` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Например: от `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 +``` ### Hotfix branch diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 44a5785..3703a6a 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:16:21 (1789269381) +completed: 2026-09-13 03:23:04 (1789269784) cancelled: value: V2 complexity: C2 @@ -243,3 +243,4 @@ git diff --check | 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, ссылки, задача и установка документов | From 6b4b9c4dda7b0b8d0403d99c39f76c0ab5ca4bf0 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:32:34 +0700 Subject: [PATCH 31/40] =?UTF-8?q?docs(branches):=20scope=20synchronization?= =?UTF-8?q?=20/=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D0=B8=D1=82=D1=8C?= =?UTF-8?q?=20=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=B0=20=D1=81=D0=B8?= =?UTF-8?q?=D0=BD=D1=85=D1=80=D0=BE=D0=BD=D0=B8=D0=B7=D0=B0=D1=86=D0=B8?= =?UTF-8?q?=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 77 ++++++++++++++----- ...K-docs-align-workflow-instructions.todo.md | 3 +- 2 files changed, 61 insertions(+), 19 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index d609c89..38cfe98 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -31,6 +31,8 @@ package: prikotov/git-workflow - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. - Перед стартом убедись, что рабочее дерево чистое: `git status`. - Если есть чужие незакоммиченные изменения — остановись и уточни у пользователя. +- Если не уверен, использовать слияние (merge) или перенос коммитов (rebase), уточни у пользователя. +- Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). ## Именование @@ -43,10 +45,12 @@ package: prikotov/git-workflow - `release/0.9.3` - `hotfix/0.9.3-login-timeout` -## Откуда создавать ветки +## Создание и синхронизация веток ### Task branch +#### Создание + Для обычных задач база и цель PR — основная ветка. Документы будущего релиза можно дополнять в этих же задачах. ```bash @@ -58,8 +62,31 @@ git pull --ff-only origin "${base#origin/}" && git switch -c task/ ``` +#### Синхронизация + +Синхронизируй `task/*` с основной веткой до окончательного одобрения PR. Находясь в ветке задачи, получи актуальное состояние основной ветки: + +```bash +git fetch origin && +git remote set-head origin --auto +``` + +Затем используй **один** согласованный способ — merge: + +```bash +git merge origin/HEAD +``` + +Или rebase: + +```bash +git rebase origin/HEAD +``` + ### Release branch +#### Создание + Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска. Для обычного релиза создай ветку от актуальной основной: [процесс релиза](release.md#1-финализация-в-релизной-ветке). @@ -77,7 +104,6 @@ git fetch origin && Правила для ветки обычного релиза: - коммить исправления, версии и релизные документы в этой ветке; - направляй PR из неё в основную ветку; слей PR до публикации тега; -- PR обычных задач направляй в основную ветку; перед окончательным одобрением синхронизируй с ней `release/x.y.z`; - продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую. Для срочного исправления создай `release/x.y.z` нового выпуска от текущего рабочего тега `vX.Y.Z` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Например: от `v1.2.0` — новую `release/1.2.1`, не меняя `release/1.2.0`. @@ -88,8 +114,33 @@ git fetch origin --tags --prune && git push -u origin release/x.y.z ``` +#### Синхронизация + +**Обычный релиз:** синхронизируй `release/x.y.z` с основной веткой до окончательного одобрения PR. Находясь в релизной ветке, получи актуальное состояние основной ветки: + +```bash +git fetch origin && +git remote set-head origin --auto +``` + +Затем используй **один** согласованный способ — merge: + +```bash +git merge origin/HEAD +``` + +Или rebase: + +```bash +git rebase origin/HEAD +``` + +**Срочное исправление:** до публикации GitHub Release принимай изменения в `release/x.y.z` только через PR из `hotfix/*` и не подтягивай в неё основную ветку. После публикации при подготовке PR возврата в основную ветку выполняй необходимую адаптацию в этой релизной ветке, используя команды синхронизации выше. + ### Hotfix branch +#### Создание + Создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`, не от вершины сохранённой релизной ветки. В имени `hotfix/x.y.z-` укажи версию нового выпуска. ```bash @@ -99,34 +150,24 @@ git switch -c hotfix/x.y.z- vX.Y.Z Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега. После выпуска верни исправление отдельным PR из этой релизной ветки в основную по [сценарию срочного исправления](release.md#hotfix-и-patch-release). -## Синхронизация +#### Синхронизация -- Синхронизируй `task/*` и ветку обычного релиза с основной веткой до окончательного одобрения PR. -- Синхронизируй `hotfix/*` с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. -- До срочного выпуска не подтягивай основную ветку в `hotfix/*` или его `release/x.y.z`. Адаптацию к основной ветке выполняй после выпуска в этой релизной ветке при подготовке PR возврата. -- Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя. +Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку в `hotfix/*`. -Для обычной задачи или обычного релиза получи актуальное состояние основной ветки: +Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и используй **один** согласованный способ — merge: ```bash git fetch origin && -git remote set-head origin --auto -``` - -Затем используй **один** согласованный способ — merge: - -```bash -git merge origin/HEAD +git merge origin/release/x.y.z ``` Или rebase: ```bash -git rebase origin/HEAD +git fetch origin && +git rebase origin/release/x.y.z ``` -Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). - ## Завершение - Удали `task/*` локально и в `origin` после слияния PR. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 3703a6a..9ac5455 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:23:04 (1789269784) +completed: 2026-09-13 03:32:34 (1789270354) cancelled: value: V2 complexity: C2 @@ -244,3 +244,4 @@ git diff --check | 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, ссылки, задача и установка документов | From 97eab34ade03af0289e6dfc889001b7bc8b2043c Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:38:25 +0700 Subject: [PATCH 32/40] =?UTF-8?q?docs(branches):=20restore=20purpose=20des?= =?UTF-8?q?criptions=20/=20=D0=B2=D0=B5=D1=80=D0=BD=D1=83=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BD=D0=B0=D0=B7=D0=BD=D0=B0=D1=87=D0=B5=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D0=B2=D0=B5=D1=82=D0=BE=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 6 ++++++ todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 38cfe98..3148467 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -49,6 +49,8 @@ package: prikotov/git-workflow ### Task branch +Используется для обычной разработки и документации. + #### Создание Для обычных задач база и цель PR — основная ветка. Документы будущего релиза можно дополнять в этих же задачах. @@ -85,6 +87,8 @@ git rebase origin/HEAD ### Release branch +Используется для подготовки одной конкретной версии — обычного релиза или срочного исправления. + #### Создание Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска. @@ -139,6 +143,8 @@ git rebase origin/HEAD ### Hotfix branch +Используется для срочного исправления ошибки в рабочей версии без нарушения совместимости. + #### Создание Создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`, не от вершины сохранённой релизной ветки. В имени `hotfix/x.y.z-` укажи версию нового выпуска. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 9ac5455..0c0f500 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:32:34 (1789270354) +completed: 2026-09-13 03:38:25 (1789270705) cancelled: value: V2 complexity: C2 @@ -245,3 +245,4 @@ git diff --check | 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, ссылки, задача, проверки структуры и синхронизации, установка документов — успешно | From db819f649059970e3d6857320b2ddf2ba16646b7 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 10:49:08 +0700 Subject: [PATCH 33/40] =?UTF-8?q?docs(branches):=20require=20merge=20synch?= =?UTF-8?q?ronization=20/=20=D1=81=D0=B8=D0=BD=D1=85=D1=80=D0=BE=D0=BD?= =?UTF-8?q?=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D1=87?= =?UTF-8?q?=D0=B5=D1=80=D0=B5=D0=B7=20merge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 27 +++---------------- ...K-docs-align-workflow-instructions.todo.md | 4 ++- 2 files changed, 7 insertions(+), 24 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 3148467..63906fb 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -31,7 +31,7 @@ package: prikotov/git-workflow - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения. - Перед стартом убедись, что рабочее дерево чистое: `git status`. - Если есть чужие незакоммиченные изменения — остановись и уточни у пользователя. -- Если не уверен, использовать слияние (merge) или перенос коммитов (rebase), уточни у пользователя. +- Для синхронизации веток используй только слияние (merge), без переписывания существующих коммитов. - Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). ## Именование @@ -73,18 +73,12 @@ git fetch origin && git remote set-head origin --auto ``` -Затем используй **один** согласованный способ — merge: +Затем выполни слияние: ```bash git merge origin/HEAD ``` -Или rebase: - -```bash -git rebase origin/HEAD -``` - ### Release branch Используется для подготовки одной конкретной версии — обычного релиза или срочного исправления. @@ -127,18 +121,12 @@ git fetch origin && git remote set-head origin --auto ``` -Затем используй **один** согласованный способ — merge: +Затем выполни слияние: ```bash git merge origin/HEAD ``` -Или rebase: - -```bash -git rebase origin/HEAD -``` - **Срочное исправление:** до публикации GitHub Release принимай изменения в `release/x.y.z` только через PR из `hotfix/*` и не подтягивай в неё основную ветку. После публикации при подготовке PR возврата в основную ветку выполняй необходимую адаптацию в этой релизной ветке, используя команды синхронизации выше. ### Hotfix branch @@ -160,20 +148,13 @@ git switch -c hotfix/x.y.z- vX.Y.Z Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку в `hotfix/*`. -Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и используй **один** согласованный способ — merge: +Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и выполни слияние: ```bash git fetch origin && git merge origin/release/x.y.z ``` -Или rebase: - -```bash -git fetch origin && -git rebase origin/release/x.y.z -``` - ## Завершение - Удали `task/*` локально и в `origin` после слияния PR. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 0c0f500..e9fbc2d 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:38:25 (1789270705) +completed: 2026-09-13 03:49:08 (1789271348) cancelled: value: V2 complexity: C2 @@ -62,6 +62,7 @@ status: done - [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. @@ -246,3 +247,4 @@ git diff --check | 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, ссылки, задача и установка документов | From 0b19712ba9f93388dc32f8c6a753e259e8f0d7ee Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 11:01:07 +0700 Subject: [PATCH 34/40] =?UTF-8?q?docs(branches):=20separate=20hotfix=20sce?= =?UTF-8?q?nario=20/=20=D0=BE=D1=82=D0=B4=D0=B5=D0=BB=D0=B8=D1=82=D1=8C=20?= =?UTF-8?q?=D1=81=D1=80=D0=BE=D1=87=D0=BD=D1=8B=D0=B9=20=D1=81=D1=86=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=D1=80=D0=B8=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 43 ++++++++++++------- ...K-docs-align-workflow-instructions.todo.md | 3 +- 2 files changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 63906fb..e634f28 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -81,7 +81,7 @@ git merge origin/HEAD ### Release branch -Используется для подготовки одной конкретной версии — обычного релиза или срочного исправления. +Используется для подготовки обычного релиза. #### Создание @@ -104,17 +104,9 @@ git fetch origin && - направляй PR из неё в основную ветку; слей PR до публикации тега; - продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую. -Для срочного исправления создай `release/x.y.z` нового выпуска от текущего рабочего тега `vX.Y.Z` по [сценарию срочного исправления](release.md#hotfix-и-patch-release). Например: от `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 -``` - #### Синхронизация -**Обычный релиз:** синхронизируй `release/x.y.z` с основной веткой до окончательного одобрения PR. Находясь в релизной ветке, получи актуальное состояние основной ветки: +Синхронизируй `release/x.y.z` с основной веткой до окончательного одобрения PR. Находясь в релизной ветке, получи актуальное состояние основной ветки: ```bash git fetch origin && @@ -127,26 +119,34 @@ git remote set-head origin --auto git merge origin/HEAD ``` -**Срочное исправление:** до публикации GitHub Release принимай изменения в `release/x.y.z` только через PR из `hotfix/*` и не подтягивай в неё основную ветку. После публикации при подготовке PR возврата в основную ветку выполняй необходимую адаптацию в этой релизной ветке, используя команды синхронизации выше. - ### Hotfix branch Используется для срочного исправления ошибки в рабочей версии без нарушения совместимости. #### Создание -Создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`, не от вершины сохранённой релизной ветки. В имени `hotfix/x.y.z-` укажи версию нового выпуска. +Для нового выпуска имена веток и тег новой версии должны быть свободны локально и в `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 switch -c hotfix/x.y.z- vX.Y.Z ``` -Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега. После выпуска верни исправление отдельным PR из этой релизной ветки в основную по [сценарию срочного исправления](release.md#hotfix-и-patch-release). +Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release). #### Синхронизация -Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку в `hotfix/*`. +Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку ни в `hotfix/*`, ни в целевую `release/x.y.z`; изменения в целевую ветку принимай только через PR из `hotfix/*`. Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и выполни слияние: @@ -155,6 +155,19 @@ 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 remote set-head origin --auto && +git switch release/x.y.z && +git merge origin/HEAD +``` + +После адаптации повтори проверки и получи одобрение PR. Не меняй опубликованный тег. + ## Завершение - Удали `task/*` локально и в `origin` после слияния PR. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index e9fbc2d..93c4344 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 03:49:08 (1789271348) +completed: 2026-09-13 04:01:07 (1789272067) cancelled: value: V2 complexity: C2 @@ -248,3 +248,4 @@ git diff --check | 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, ссылки, задача и установка документов | From ab72b312fedd61bbbf977ddd0e3169d0e6bea369 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Sun, 13 Sep 2026 21:58:50 +0700 Subject: [PATCH 35/40] =?UTF-8?q?docs(branches):=20group=20lifecycle=20by?= =?UTF-8?q?=20type=20/=20=D1=81=D0=B3=D1=80=D1=83=D0=BF=D0=BF=D0=B8=D1=80?= =?UTF-8?q?=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D0=B6=D0=B8=D0=B7=D0=BD=D0=B5?= =?UTF-8?q?=D0=BD=D0=BD=D1=8B=D0=B9=20=D1=86=D0=B8=D0=BA=D0=BB=20=D0=B2?= =?UTF-8?q?=D0=B5=D1=82=D0=BE=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 47 +++++++++++++------ ...K-docs-align-workflow-instructions.todo.md | 3 +- 2 files changed, 34 insertions(+), 16 deletions(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index e634f28..1f3f0ca 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -34,22 +34,17 @@ package: prikotov/git-workflow - Для синхронизации веток используй только слияние (merge), без переписывания существующих коммитов. - Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr). -## Именование +## Работа с ветками -- `task/` — английский, `kebab-case`, кратко по смыслу. -- `release/x.y.z` — полный номер выпуска по `major.minor.patch`. -- `hotfix/x.y.z-` — patch version плюс короткое описание. +### Task branch -Примеры: -- `task/docs-release-workflow` -- `release/0.9.3` -- `hotfix/0.9.3-login-timeout` +Используется для обычной разработки и документации. -## Создание и синхронизация веток +#### Именование -### Task branch +`task/` — короткое описание на английском в `kebab-case`. -Используется для обычной разработки и документации. +Пример: `task/docs-release-workflow`. #### Создание @@ -79,10 +74,20 @@ git remote set-head origin --auto git merge origin/HEAD ``` +#### Завершение + +Удали `task/*` локально и в `origin` после слияния PR. + ### Release branch Используется для подготовки обычного релиза. +#### Именование + +`release/x.y.z` — полный номер выпуска по `major.minor.patch`. + +Пример: `release/0.9.3`. + #### Создание Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска. @@ -119,10 +124,22 @@ git remote set-head origin --auto git merge origin/HEAD ``` +#### Завершение + +- Сохраняй `release/x.y.z` и тег выпуска локально и в `origin`. +- Не удаляй релизную ветку при слиянии PR и не переиспользуй для другой версии. +- Отменённого кандидата не тегируй. + ### Hotfix branch Используется для срочного исправления ошибки в рабочей версии без нарушения совместимости. +#### Именование + +`hotfix/x.y.z-` — версия нового патч-релиза и короткое описание на английском в `kebab-case`. + +Пример: `hotfix/0.9.3-login-timeout`. + #### Создание Для нового выпуска имена веток и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. @@ -168,8 +185,8 @@ git merge origin/HEAD После адаптации повтори проверки и получи одобрение PR. Не меняй опубликованный тег. -## Завершение +#### Завершение -- Удали `task/*` локально и в `origin` после слияния PR. -- Сохраняй все `release/*` локально и в `origin`, а также теги выпусков. Не удаляй релизную ветку при слиянии PR и не переиспользуй для другой версии. Отменённого кандидата не тегируй. -- Удали `hotfix/*` после выпуска и слияния исправления в основную ветку. +- Удали `hotfix/*` локально и в `origin` после публикации GitHub Release и слияния исправления в основную ветку. +- Сохраняй целевую `release/x.y.z` и тег выпуска локально и в `origin`; не удаляй ветку при слиянии PR и не переиспользуй для другой версии. +- Отменённого кандидата не тегируй. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 93c4344..240308b 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 04:01:07 (1789272067) +completed: 2026-09-13 14:58:50 (1789311530) cancelled: value: V2 complexity: C2 @@ -249,3 +249,4 @@ git diff --check | 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, ссылки, задача и установка документов | From e89d9d5ee30ec1e31591478980d36f3e5c73d12d Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Mon, 14 Sep 2026 09:16:56 +0700 Subject: [PATCH 36/40] =?UTF-8?q?docs(git):=20explain=20default=20branch?= =?UTF-8?q?=20commands=20/=20=D0=BF=D0=BE=D1=8F=D1=81=D0=BD=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20=D0=BA=D0=BE=D0=BC=D0=B0=D0=BD=D0=B4=D1=8B=20=D0=BE?= =?UTF-8?q?=D1=81=D0=BD=D0=BE=D0=B2=D0=BD=D0=BE=D0=B9=20=D0=B2=D0=B5=D1=82?= =?UTF-8?q?=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/branches.md | 9 +++++++++ docs/git-workflow/release.md | 4 ++++ todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/git-workflow/branches.md b/docs/git-workflow/branches.md index 1f3f0ca..9fd1296 100644 --- a/docs/git-workflow/branches.md +++ b/docs/git-workflow/branches.md @@ -52,8 +52,11 @@ package: prikotov/git-workflow ```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 task/ @@ -65,6 +68,7 @@ git switch -c task/ ```bash git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. git remote set-head origin --auto ``` @@ -96,8 +100,11 @@ git merge origin/HEAD ```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 && @@ -115,6 +122,7 @@ git fetch origin && ```bash git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. git remote set-head origin --auto ``` @@ -178,6 +186,7 @@ git merge origin/release/x.y.z ```bash git fetch origin && +# Обновить локальный указатель основной ветки по данным origin. git remote set-head origin --auto && git switch release/x.y.z && git merge origin/HEAD diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 40c65be..8967bd6 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -102,8 +102,11 @@ git diff ```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 && @@ -126,6 +129,7 @@ git fetch origin && 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" -- diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 240308b..8f443dd 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-13 14:58:50 (1789311530) +completed: 2026-09-14 02:16:56 (1789352216) cancelled: value: V2 complexity: C2 @@ -250,3 +250,4 @@ git diff --check | 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, ссылки, задача и установка документов — успешно | From bf8df8a68ff27fe78c59059ce6a9d152f89d2cc2 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Mon, 14 Sep 2026 09:43:56 +0700 Subject: [PATCH 37/40] =?UTF-8?q?docs(deploy):=20remove=20redundant=20glos?= =?UTF-8?q?sary=20link=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=BB?= =?UTF-8?q?=D0=B8=D1=88=D0=BD=D1=8E=D1=8E=20=D1=81=D1=81=D1=8B=D0=BB=D0=BA?= =?UTF-8?q?=D1=83=20=D0=BD=D0=B0=20=D1=81=D0=BB=D0=BE=D0=B2=D0=B0=D1=80?= =?UTF-8?q?=D1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/deploy.md | 2 +- todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index f2f7cbd..1f31a64 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -4,7 +4,7 @@ package: prikotov/git-workflow # Деплой (Deploy) -**[Выкладка (Deployment, deploy)](glossary.md#deployment)** — установка выбранной версии в рабочую среду с необходимыми действиями: обновление кода, установка зависимостей, миграции, прогрев кэша, перезапуск или перезагрузка сервисов. +**Выкладка (Deployment, deploy)** — установка выбранной версии в рабочую среду с необходимыми действиями: обновление кода, установка зависимостей, миграции, прогрев кэша, перезапуск или перезагрузка сервисов. ## Границы ответственности diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 8f443dd..aeb81f8 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-14 02:16:56 (1789352216) +completed: 2026-09-14 02:43:56 (1789353836) cancelled: value: V2 complexity: C2 @@ -251,3 +251,4 @@ git diff --check | 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, ссылки, задача и установка документов | From 5f6382dcf80c9f6b00f53c1420b5d329ed745493 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Mon, 14 Sep 2026 09:53:23 +0700 Subject: [PATCH 38/40] =?UTF-8?q?docs(deploy):=20remove=20duplicate=20rest?= =?UTF-8?q?riction=20/=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=BF?= =?UTF-8?q?=D0=BE=D0=B2=D1=82=D0=BE=D1=80=D1=8F=D1=8E=D1=89=D0=B8=D0=B9?= =?UTF-8?q?=D1=81=D1=8F=20=D0=B7=D0=B0=D0=BF=D1=80=D0=B5=D1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/deploy.md | 1 - todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index 1f31a64..d7156c9 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -16,7 +16,6 @@ package: prikotov/git-workflow ## Правила - Production deploy выполняется только по **конкретному release tag** `vX.Y.Z`. -- Выкладка из вершины ветки запрещена. - Если релиз включает миграции — деплой должен учитывать порядок действий и риски. - Production incidents после деплоя закрываются через hotfix или patch release, а не через rollback. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index aeb81f8..8e0a44e 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-14 02:43:56 (1789353836) +completed: 2026-09-14 02:53:23 (1789354403) cancelled: value: V2 complexity: C2 @@ -252,3 +252,4 @@ git diff --check | 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, ссылки, задача и установка документов | From a25c2471c24848b3c565968173953fe3a217597a Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Mon, 14 Sep 2026 09:59:44 +0700 Subject: [PATCH 39/40] =?UTF-8?q?docs(deploy):=20require=20version-specifi?= =?UTF-8?q?c=20actions=20/=20=D0=B2=D1=8B=D0=BF=D0=BE=D0=BB=D0=BD=D1=8F?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B4=D0=B5=D0=B9=D1=81=D1=82=D0=B2=D0=B8=D1=8F?= =?UTF-8?q?=20=D0=BF=D0=BB=D0=B0=D0=BD=D0=B0=20=D0=B2=D0=B5=D1=80=D1=81?= =?UTF-8?q?=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/deploy.md | 2 ++ todo/done/TASK-docs-align-workflow-instructions.todo.md | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/git-workflow/deploy.md b/docs/git-workflow/deploy.md index d7156c9..75a6843 100644 --- a/docs/git-workflow/deploy.md +++ b/docs/git-workflow/deploy.md @@ -27,6 +27,8 @@ package: prikotov/git-workflow ## Рекомендуемый поток +**Выполняй подготовительные и завершающие действия из `docs/releases/vX.Y.Z/` на указанных там этапах.** Эти инструкции дополняют при выполнении задач. + 1. Подготовить выпуск по [процессу релиза](release.md#выпуск-релиза) или [сценарию срочного исправления](release.md#hotfix-и-patch-release), пройти обязательные проверки выбранного сценария и опубликовать тег. 2. Развернуть выбранный тег `vX.Y.Z` по инструкции выкладки проекта (runbook). 3. Проверить основные пользовательские сценарии, логи и метрики. diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index 8e0a44e..ee8c69d 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-14 02:53:23 (1789354403) +completed: 2026-09-14 02:59:44 (1789354784) cancelled: value: V2 complexity: C2 @@ -253,3 +253,4 @@ git diff --check | 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, ссылки, задача и установка документов | From 5579ddf701ece4a19d4b63447d3cd212f000b35d Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Mon, 14 Sep 2026 11:03:40 +0700 Subject: [PATCH 40/40] =?UTF-8?q?docs(checks):=20defer=20commands=20to=20p?= =?UTF-8?q?rojects=20/=20=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=BA=D0=BE?= =?UTF-8?q?=D0=BC=D0=B0=D0=BD=D0=B4=D1=8B=20=D0=B8=D0=B7=20=D0=BF=D1=80?= =?UTF-8?q?=D0=B0=D0=B2=D0=B8=D0=BB=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82?= =?UTF-8?q?=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/code-review.md | 2 +- docs/git-workflow/pull-request.md | 5 +++-- docs/git-workflow/release-checklists.md | 4 ++-- docs/git-workflow/release.md | 10 +++++----- .../templates/hotfix-release-plan.template.md | 2 +- docs/git-workflow/templates/release-plan.template.md | 4 ++-- .../done/TASK-docs-align-workflow-instructions.todo.md | 9 +++++---- 7 files changed, 19 insertions(+), 17 deletions(-) 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/pull-request.md b/docs/git-workflow/pull-request.md index c1a84e9..262a278 100644 --- a/docs/git-workflow/pull-request.md +++ b/docs/git-workflow/pull-request.md @@ -47,11 +47,12 @@ package: prikotov/git-workflow ## Обязательные проверки -- По умолчанию перед PR обязателен успешный `make check`, в том числе для `docs-only` и служебных изменений. +- По умолчанию перед PR должны успешно пройти проверки проекта, в том числе для `docs-only` и служебных изменений. +- Набор проверок и команды запуска бери из документации проекта. Если они не определены, уточни у пользователя. - Пропуск или замена проверки допустимы только по явной политике проекта-потребителя (например, в его `AGENTS.md`): должны быть указаны применимые категории изменений и необходимые проверки вместо пропущенной. - Отсутствие команды или сбой окружения не разрешают пропуск проверки. - В PR укажи выполненные команды, результаты и ссылку на применимое проектное исключение, если оно использовано. -- Исключение для `make check` не отменяет остальные обязательные проверки и CI, если политика явно не определяет иное. +- Исключение для одной проверки не отменяет остальные обязательные проверки и CI, если политика явно не определяет иное. ## Создание PR diff --git a/docs/git-workflow/release-checklists.md b/docs/git-workflow/release-checklists.md index de59a0e..d93aea2 100644 --- a/docs/git-workflow/release-checklists.md +++ b/docs/git-workflow/release-checklists.md @@ -19,7 +19,7 @@ package: prikotov/git-workflow - Исправления, `CHANGELOG.md`, файлы версий и итоговый план закоммичены в `release/x.y.z` вручную, без автоматического тега. - PR (запрос на слияние) открыт из `release/x.y.z` в основную ветку; синхронизация завершена до окончательного одобрения. - Все изменения, включая данные задачи, закоммичены до окончательных проверок и одобрения PR. -- Перед релизом выполнен `make check` с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты `make tests-e2e`; проверки успешны. +- Перед релизом выполнены проверки проекта с учётом [явных проектных исключений](pull-request.md#обязательные-проверки) и обязательно запущены сквозные тесты; проверки успешны. - Автоматические проверки PR (CI) успешны. Пользователь одобрил проверенный PR и подтвердил слияние; PR слит через GitHub. - Коммит слияния входит в историю основной ветки и совпадает по содержимому с одобренным коммитом `release/x.y.z`; оба SHA зафиксированы: [проверка коммита выпуска](release.md#2-проверка-коммита-выпуска). - После разрешения на выпуск неизменяемый тег создан на выбранном коммите; опубликован только этот тег по [процессу релиза](release.md#выпуск-релиза). @@ -32,7 +32,7 @@ package: prikotov/git-workflow - Объём срочного исправления минимален и не тянет несвязанные изменения. - Имя ветки и тег соответствуют новой полной версии. Ветки предыдущих и параллельно готовящихся выпусков не переиспользованы и не перезаписаны. - Исправление и файлы патч-релиза подготовлены в `hotfix/*`; синхронизация с целевой `release/x.y.z` завершена до одобрения. -- Перед срочным выпуском выполнен `make check` по правилам проекта; проверки и CI успешны. +- Перед срочным выпуском выполнены проверки по правилам проекта; проверки и CI успешны. - Если пользователь явно запросил сквозные тесты, они выполнены успешно; без запроса не запускались. - Проверенный PR из `hotfix/*` в `release/x.y.z` нового выпуска одобрен и слит через GitHub с подтверждением пользователя. - Коммит слияния входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`; оба SHA зафиксированы. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 8967bd6..58bf20a 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -81,8 +81,8 @@ git diff - Замените `X.Y.Z` выбранной версией без префикса `v`; `--merged` ограничивает историю коммитами, достижимыми из `HEAD`. - Не используйте `--commit`, `--commit-all` или `--amend`. Проверьте конфигурацию `.changelog` и её callbacks: они тоже не должны создавать коммиты, теги или выполнять публикацию. - Команда изменяет файлы. Проверьте весь diff, включая `CHANGELOG.md` и файлы версий. -- Если генератор не установлен, подготовьте файлы вручную по тем же правилам. Этот пакет не поставляет генератор или цели `make release-*`. -- Не запускайте обёртки `make release`, `make release-*` или `make changelog`, пока не проверены их действия. +- Если генератор не установлен, подготовьте файлы вручную по тем же правилам. Этот пакет не поставляет генератор или команды подготовки релиза. +- Не запускайте проектные команды подготовки релиза или CHANGELOG, пока не проверены их действия. `CHANGELOG.md` должен оставаться коротким: - заголовок релиза; @@ -116,7 +116,7 @@ git fetch origin && 1. В `release/x.y.z` внесите исправления, обновите `CHANGELOG.md`, файлы версий и релизные документы. 2. Проверьте diff и создайте коммиты вручную по [commits.md](commits.md). 3. Откройте PR **из `release/x.y.z` в основную ветку** по [правилам PR](pull-request.md). -4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните `make check` и обязательный предрелизный запуск `make tests-e2e`; дождитесь успеха. Проектные исключения для `make check` не отменяют сквозные тесты. +4. До окончательного одобрения синхронизируйтесь с основной веткой и завершите все правки, включая служебные обновления задачи. Выполните проверки проекта и обязательный предрелизный запуск сквозных тестов; дождитесь успеха. Проектные исключения для других проверок не отменяют сквозные тесты. 5. Зафиксируйте SHA проверенного состояния `release/x.y.z`. Дождитесь успешных автоматических проверок PR (CI), одобрения и подтверждения слияния пользователем. Выполните слияние через GitHub. Доработки требуют [повторного одобрения](pull-request.md#подготовка-pr). ### 2. Проверка коммита выпуска @@ -177,11 +177,11 @@ git fetch origin --tags --prune && До выпуска не подтягивайте основную ветку в `hotfix/*` и целевую `release/x.y.z`. -При срочном исправлении запускайте сквозные тесты только по явному запросу пользователя. Если затронут критический пользовательский сценарий, предложите точечный запуск вместо полного `make tests-e2e`. +При срочном исправлении запускайте сквозные тесты только по явному запросу пользователя. Если затронут критический пользовательский сценарий, предложите точечный запуск вместо полного прогона сквозных тестов. 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`. Завершите все правки, выполните `make check` по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. +3. До окончательного одобрения синхронизируйте `hotfix/*` с целевой `release/x.y.z`. Завершите все правки, выполните проверки по правилам проекта; дождитесь успеха всех запущенных проверок и CI. Зафиксируйте SHA проверенного коммита `hotfix/*`, получите одобрение и подтверждение слияния. Слейте PR через GitHub. 4. Получите SHA результата этого PR из GitHub. Проверьте, что коммит входит в историю целевой `release/x.y.z` и совпадает по содержимому с одобренным коммитом `hotfix/*`: ```bash diff --git a/docs/git-workflow/templates/hotfix-release-plan.template.md b/docs/git-workflow/templates/hotfix-release-plan.template.md index 45e49f0..40fc199 100644 --- a/docs/git-workflow/templates/hotfix-release-plan.template.md +++ b/docs/git-workflow/templates/hotfix-release-plan.template.md @@ -31,7 +31,7 @@ ## План проверок перед выкладкой -- Выполнить `make check` по правилам проекта; дождаться успешного результата +- Выполнить проверки по правилам проекта; дождаться успешного результата - Запускать сквозные тесты только по явному запросу пользователя; дождаться успеха запрошенных проверок - До создания тега проверить, что PR из `hotfix/*` слит в `release/x.y.z` нового выпуска - Проверить, что тег указывает на результат этого слияния, совпадающий по содержимому с одобренным коммитом `hotfix/*` и не содержащий невыпущенных изменений основной ветки diff --git a/docs/git-workflow/templates/release-plan.template.md b/docs/git-workflow/templates/release-plan.template.md index cc3317e..09458dd 100644 --- a/docs/git-workflow/templates/release-plan.template.md +++ b/docs/git-workflow/templates/release-plan.template.md @@ -32,8 +32,8 @@ ## План проверок перед выкладкой -- Выполнить `make check` по правилам проекта; дождаться успешного результата -- Обязательно выполнить `make tests-e2e`; дождаться успешного результата +- Выполнить проверки по правилам проекта; дождаться успешного результата +- Обязательно выполнить сквозные тесты; дождаться успешного результата - До создания тега проверить, что PR из `release/x.y.z` слит в основную ветку - Проверить, что тег указывает на коммит слияния PR, который совпадает по содержимому с одобренным коммитом `release/x.y.z` - Убедиться, что согласованный тег опубликован в `origin` diff --git a/todo/done/TASK-docs-align-workflow-instructions.todo.md b/todo/done/TASK-docs-align-workflow-instructions.todo.md index ee8c69d..10c615f 100644 --- a/todo/done/TASK-docs-align-workflow-instructions.todo.md +++ b/todo/done/TASK-docs-align-workflow-instructions.todo.md @@ -3,7 +3,7 @@ type: docs created: 2026-09-11 03:45:03 (1789098303) due: started: 2026-09-11 03:46:53 (1789098413) -completed: 2026-09-14 02:59:44 (1789354784) +completed: 2026-09-14 04:03:12 (1789358592) cancelled: value: V2 complexity: C2 @@ -56,7 +56,7 @@ status: done - [x] Тег обычного релиза создавать на согласованном коммите основной ветки после включения релизных файлов; не выпускать код, существующий только в релизной ветке. Для срочного исправления использовать отдельный порядок. Публиковать только конкретный тег. - [x] Устранить предписание запускать автоматическое создание коммита и тега непосредственно в релизной ветке; привести примеры к существующим возможностям инструментов без вымышленных команд. - [x] Согласовать исключения для проверок с явно заданной политикой проекта-потребителя; при отсутствии исключения сохранить обязательные проверки. -- [x] По подтверждённому запросу пользователя оставить сквозные тесты обязательными для обычного релиза, а для срочного исправления запускать только по явному запросу. Не менять требования к `make check` и CI. +- [x] По подтверждённому запросу пользователя оставить сквозные тесты обязательными для обычного релиза, а для срочного исправления запускать только по явному запросу. Сохранить требования к проверкам проекта и CI без привязки к названиям команд. - [x] Подготовку сообщений коммитов подчинить `commits.md`, убрать противоречащий обязательный помощник, привести примеры к английскому и русскому тексту через косую черту. - [x] Обновить непосредственно связанные чеклисты, чтобы они не предписывали старый порядок. - [x] Разделить шаблоны обычного релиза и срочного исправления, убрать выбор сценария и чужие пункты; сохранить общий регламент и путь заполненного `docs/releases/vX.Y.Z/release-plan.md`. @@ -92,7 +92,7 @@ git diff --check - Согласованы `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`; служебные изменения не обходят окончательное одобрение. -- Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к `make check` и CI сохранены. +- Для обычного релиза сквозные тесты обязательны; для срочного исправления — только по явному запросу пользователя. При критическом пользовательском сценарии агент предлагает точечный запуск, не запускает его самостоятельно. Требования к проверкам проекта и 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 в установленной копии, ошибок нет. @@ -106,7 +106,7 @@ git diff --check ### Доработка после замечаний пользователя -Ниже сохранена история промежуточных редакций и ошибок агента. Действующий порядок приведён в разделе «Отдельная ветка каждого выпуска»; прежние правила общей `release/x.y` и её восстановления заменены. +Ниже сохранена история промежуточных редакций и ошибок агента. Действующий порядок приведён в разделе «Отдельная ветка каждого выпуска»; прежние правила общей `release/x.y` и её восстановления заменены. Прежние предписания конкретных команд проверок также отменены: актуальная документация отсылает к правилам проекта-потребителя. - Задача возвращена в `review` перед исправлениями. Во взаимосвязанных документах явно различены имена рабочих веток, пути файлов и идентификаторы коммитов. - Сохранён обязательный предрелизный запуск `make tests-e2e`. Убрано добавленное требование полного повторного прогона и отдельного CI только из-за нового идентификатора коммита после слияния. Непроверенные изменения проверяются по правилам проекта. @@ -254,3 +254,4 @@ git diff --check | 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, ссылки, задача и установка документов |