Skip to content

docs(workflow): align branch and release instructions - #10

Merged
prikotov merged 40 commits into
masterfrom
task/align-workflow-instructions
Sep 15, 2026
Merged

prikotov merged 40 commits into
masterfrom
task/align-workflow-instructions

Conversation

@prikotov

@prikotov prikotov commented Sep 11, 2026 •

Copy link
Copy Markdown
Owner

Задача

Согласовать исходные Git-инструкции и убрать избыточные пояснения.

TASK-docs-align-workflow-instructions — done, готово к приёмке.
Связанные PR: TasK #2899, todo-md #31.

Изменения

  • Из общих правил, чеклистов и шаблонов убраны конкретные команды проверок проектов-потребителей. Набор проверок и способы запуска берутся из документации проекта; если инструкции отсутствуют, нужно уточнение пользователя. Убраны также предположения об именах проектных команд подготовки релиза.
  • В deploy.md удалена дублирующая строка «Выкладка из вершины ветки запрещена»; требование выкладки по конкретному тегу релиза сохранено. В рекомендуемом потоке выделено выполнение подготовительных и завершающих действий из docs/releases/vX.Y.Z/ на указанных там этапах; инструкции дополняются при выполнении задач. Проверены точечность дополнения, сохранение порядка шагов и требований к разрешениям.
  • В примерах branches.md и release.md добавлены короткие комментарии к git remote set-head origin --auto, чтению имени основной ветки через git symbolic-ref и удалению префикса origin/ при переключении. Уточнено, что обновляется локальный указатель; универсальность и команды сохранены.
  • branches.md: типы веток собраны в разделе «Работа с ветками». Каждая секция Task/Release/Hotfix содержит назначение, именование с примером, создание, синхронизацию и завершение; для hotfix также описан возврат в основную ветку. Общие разделы именования, синхронизации и завершения удалены; требование повторного одобрения перенесено в общие правила. Для синхронизации закреплён только merge, без переписывания существующих коммитов; три варианта rebase удалены. Команды создания веток сохранены; hotfix синхронизируется только с целевой origin/release/x.y.z. Способы интеграции PR на GitHub не менялись.
  • В branches.md сценарии разделены: Release branch описывает только обычный релиз от основной ветки; весь срочный сценарий находится в Hotfix branch, включая создание целевой release/x.y.z от рабочего тега и возврат после публикации GitHub Release. Примеры создания обеих релизных веток сохранены и совпадают с release.md; перед ними указана проверка свободных имён.
  • Оба шаблона используют конкретные действия при проблеме вместо выбора между hotfix и patch release, подсказки профилей ролей и проверку безопасного порядка обновления. Удалены дублирующие поля «Вне состава релиза» и «Риск окна несовместимости»; слияние подготовки явно требуется до создания тега.
  • Обычный шаблон сохраняет выбор и обоснование версии, плановую дату выкладки, отдельное описание несовместимых изменений и обязательные E2E. Его PR идёт из release/x.y.z в основную ветку.
  • Срочный шаблон содержит причину исправления, но не плановую дату или отдельное поле совместимости. PR исправления сливается в новую релизную ветку до создания тега; PR из неё в основную открывается после публикации GitHub Release.
  • Добавлен docs/git-workflow/glossary.md: 26 коротких определений в формате «русский термин (English) — пояснение», с отдельным стабильным якорем каждого термина. Ссылки добавлены в оглавление, README и регламент выпуска; в deploy.md определение выкладки приведено без ссылки на словарь. Публикация версии отделена от установки в рабочую среду.
  • Каждый выпуск получает отдельную release/x.y.z, включая каждый патч. Все релизные ветки и теги сохраняются. Общие release/x.y больше не используются; ветки других выпусков не переиспользуются и не перезаписываются.
  • Обычный релиз: актуальная основная ветка → финализация и коммиты в новой release/x.y.z → PR в основную → проверенный результат слияния → тег. Основная ветка определяется через актуальный origin/HEAD, без ручной замены master/main.
  • Срочное исправление v1.2.0: новые release/1.2.1 и hotfix/1.2.1-… от рабочего тега → одобренный PR исправления в release/1.2.1 → слияние → тег v1.2.1 на проверенном результате → выпуск → PR из release/1.2.1 в основную. Старая release/1.2.0 не меняется.
  • До срочного выпуска основная ветка не подтягивается в обе новые ветки. После выпуска конфликты возврата разрешаются в релизной ветке с повторными проверками и одобрением; временная ветка не нужна. Следующий патч начинается от рабочего тега, не от изменённой вершины сохранённой ветки.
  • Для обоих сценариев проверяются принадлежность результата PR целевой ветке и совпадение содержимого с одобренным состоянием. Более поздний коммит не подменяет выбранный результат; опубликованный тег неизменяем.
  • Документы релиза пополняются в обычных задачах. Разделены шаблоны обычного релиза и срочного исправления; изменяемые поля и оба заголовка используют предметные подсказки. Заполненный план не перезаписывается шаблоном. В срочном плане вместо обоснования версии указывается причина исправления — описание ошибки; удалены лишние поля «Плановая дата deploy» и «Вне состава релиза».
  • Сквозные тесты обычного релиза обязательны; срочного исправления — только по явному запросу. Требования к проверкам проекта и CI сохранены без привязки к конкретным командам.
  • Согласованы разрешения пользователя, ручные двуязычные Conventional Commits, проектные исключения проверок и завершение задач до окончательного одобрения. После завершения удаляются task/* и hotfix/*, но не release/*.
  • Исправлена обнаруженная проверками ошибка примера: при неудачном git fetch создание hotfix/* теперь останавливается.

Проверки

  • Проверено отсутствие make-команд в распространяемой документации, сохранение условий сквозных тестов для обоих сценариев и проектных исключений. Примеры Git-команд, ветки и инструкция выкладки не изменились. Повторены 774 проверки Git-модели и проверка установки всех 13 документов.
    Личная вычитка без делегирования; проверялась согласованная модель отдельных выпусков, не прежняя общая линия.

  • composer validate --strict — успешно; приватных зависимостей нет.

  • Валидация задачи, git diff --check, локальные ссылки и якоря — успешно. Удаление ссылки в deploy.md проверено отдельно: определение и правила сохранены. При пояснении команд проверено добавление только 13 комментариев без изменения команд и другого текста; синтаксис всех затронутых Bash-примеров проверен через bash -n.

  • Повторены 774 проверки Git-модели на восстановленных примерах из branches.md, проверено точное совпадение команд с release.md: два последовательных патча и следующий обычный релиз; master, main, team/main; merge/squash/rebase первой интеграции; прямой возврат с конфликтами; сохранность всех выпусков; отказы до слияния, при неверном составе, занятом имени, отсутствующем теге и недоступном репозитории. Это изолированные локальные репозитории, не настоящие PR или тесты приложения.

  • Проверены точечность перехода на синхронизацию только через merge, структура документа и сохранение команд создания веток. Три сценария синхронизации hotfix: успешное слияние целевой ветки, недоступный origin и отсутствующая целевая ветка. Существующие коммиты сохраняются, невыпущенные изменения основной ветки не попадают в hotfix; теги и удалённые ветки не изменяются. Отдельно выполнен пример возврата после моделируемой публикации: адаптируется только релизная ветка, hotfix и опубликованные теги сохраняются. Проверено отсутствие срочного сценария в секции Release branch. После переноса именования и завершения проверены порядок подразделов, сохранение примеров имён, правил удаления и хранения веток и тегов; все команды и их порядок остались прежними.

  • Повторены 30 проверок команд origin/HEAD: разные имена и состояния ссылки, создание задачи, синхронизация task/release через merge с сохранением существующих коммитов и остановка при ошибках подготовки.

  • Проверены подсказки шаблонов, точный состав изменений и неизменность условий E2E. Обычный шаблон согласован со срочным по общим разделам; отдельно проверены сохранение выбора версии, плановой даты, описания несовместимых изменений и обязательных E2E. Последняя правка не меняет срочный шаблон. Словарь проверен на формат всех 26 определений, уникальность якорей и отображение Markdown. Установка и повторная установка 13 документов в стандартный и нестандартный каталоги совпадают с исходниками; без --force пользовательские файлы сохранены, с --force обновлены конвенции без изменения заполненного плана.

  • Отдельных статического и архитектурного анализаторов в CI пакета нет. Изменена только документация; тесты приложения не запускались.

Ограничения

CI пакета пока запускается только для PR в master/main. Перед реальным срочным выпуском отдельно согласовать включение release/* в CI. Настройки сейчас не менялись; автоматическое удаление исходных веток после слияния в git-workflow и TasK отключено.

Код, конфигурации, зависимости и установленные копии TasK не изменены. Слияние этих PR, выпуски и теги в реальных репозиториях не выполнялись.

@prikotov prikotov added the pi Pi Coding Agent label Sep 11, 2026
@prikotov
prikotov marked this pull request as ready for review September 11, 2026 04:03
@prikotov
prikotov merged commit 6530aa1 into master Sep 15, 2026
1 check passed
@prikotov
prikotov deleted the task/align-workflow-instructions branch September 15, 2026 02:13
@prikotov prikotov mentioned this pull request Sep 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pi Pi Coding Agent

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant