From 22bc04475ec21faaeaae828446685c3ab21c56c2 Mon Sep 17 00:00:00 2001 From: Dmitry Prikotov Date: Tue, 22 Sep 2026 07:40:30 +0700 Subject: [PATCH 1/5] =?UTF-8?q?docs(glossary):=20replace=20HTML=20anchors?= =?UTF-8?q?=20with=20pure=20markdown=20headings=20/=20=D0=B7=D0=B0=D0=BC?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=82=D1=8C=20HTML-=D1=8F=D0=BA=D0=BE=D1=80?= =?UTF-8?q?=D1=8F=20=D1=87=D0=B8=D1=81=D1=82=D1=8B=D0=BC=20Markdown?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git-workflow/glossary.md | 132 +++++++++++------- docs/git-workflow/release.md | 2 +- .../TASK-fix-glossary-pure-md-anchors.todo.md | 87 ++++++++++++ 3 files changed, 167 insertions(+), 54 deletions(-) create mode 100644 todo/TASK-fix-glossary-pure-md-anchors.todo.md diff --git a/docs/git-workflow/glossary.md b/docs/git-workflow/glossary.md index 28837c9..fe9a295 100644 --- a/docs/git-workflow/glossary.md +++ b/docs/git-workflow/glossary.md @@ -4,90 +4,116 @@ package: prikotov/git-workflow # Словарь терминов (Glossary) -Термины используются в значениях ниже. На отдельное определение можно ссылаться по якорю, например: [выкладка](#deployment). +Термины используются в значениях ниже. На отдельное определение можно ссылаться по якорю, например: [выкладка](#выкладка-deployment-deploy). ## Репозиторий и ветки - -**Репозиторий (Repository)** — хранилище файлов проекта и истории их изменений в Git. +### Репозиторий (Repository) - -**Ветка (Branch)** — именованная линия разработки, указатель которой перемещается при добавлении коммитов. +Хранилище файлов проекта и истории их изменений в Git. - -**Основная ветка (Main branch)** — ветка по умолчанию репозитория, в которую включаются согласованные изменения и от которой готовятся обычные релизы. +### Ветка (Branch) - -**Релизная ветка (Release branch)** — ветка подготовки одной конкретной версии, например `release/1.2.1`. В этом процессе сохраняется после выпуска и не переиспользуется для другой версии. +Именованная линия разработки, указатель которой перемещается при добавлении коммитов. - -**Коммит (Commit)** — запись в истории Git, фиксирующая состояние файлов, автора, сообщение и связь с предыдущей историей. +### Основная ветка (Main branch) - -**Идентификатор коммита (Commit SHA)** — хеш, по которому Git однозначно находит конкретный коммит, независимо от последующих изменений ветки. +Ветка по умолчанию репозитория, в которую включаются согласованные изменения и от которой готовятся обычные релизы. - -**Тег релиза (Release tag)** — именованная отметка коммита выпуска, например `v1.2.1`. В этом процессе опубликованный тег неизменяем. +### Релизная ветка (Release branch) + +Ветка подготовки одной конкретной версии, например `release/1.2.1`. В этом процессе сохраняется после выпуска и не переиспользуется для другой версии. + +### Коммит (Commit) + +Запись в истории Git, фиксирующая состояние файлов, автора, сообщение и связь с предыдущей историей. + +### Идентификатор коммита (Commit SHA) + +Хеш, по которому Git однозначно находит конкретный коммит, независимо от последующих изменений ветки. + +### Тег релиза (Release tag) + +Именованная отметка коммита выпуска, например `v1.2.1`. В этом процессе опубликованный тег неизменяем. ## Проверка и включение изменений - -**Запрос на слияние (Pull Request, PR)** — предложение включить изменения из исходной ветки в целевую; содержит обсуждение, результаты проверок и решение по изменениям. +### Запрос на слияние (Pull Request, PR) + +Предложение включить изменения из исходной ветки в целевую; содержит обсуждение, результаты проверок и решение по изменениям. + +### Ревью кода (Code review) + +Проверка предложенных изменений человеком или агентом: корректности, понятности и соответствия правилам проекта. + +### Одобрение (Approval) + +Подтверждение, что проверенное состояние изменений принято проверяющим. Разрешения на слияние и выпуск определяются отдельно по [правилам PR](pull-request.md). + +### Слияние веток (Merge) - -**Ревью кода (Code review)** — проверка предложенных изменений человеком или агентом: корректности, понятности и соответствия правилам проекта. +Объединение истории разработки для включения изменений одной ветки в другую. - -**Одобрение (Approval)** — подтверждение, что проверенное состояние изменений принято проверяющим. Разрешения на слияние и выпуск определяются отдельно по [правилам PR](pull-request.md). +### Объединение коммитов (Squash) - -**Слияние веток (Merge)** — объединение истории разработки для включения изменений одной ветки в другую. +Сведение изменений нескольких коммитов в один новый коммит. - -**Объединение коммитов (Squash)** — сведение изменений нескольких коммитов в один новый коммит. +### Перенос коммитов (Rebase) - -**Перенос коммитов (Rebase)** — повторное применение изменений коммитов к новой базе; пересозданные коммиты получают новые идентификаторы. +Повторное применение изменений коммитов к новой базе; пересозданные коммиты получают новые идентификаторы. - -**Непрерывная интеграция (Continuous Integration, CI)** — регулярное объединение изменений, сопровождаемое автоматической сборкой и проверками. +### Непрерывная интеграция (Continuous Integration, CI) - -**Сквозные тесты (End-to-end tests, E2E)** — проверки пользовательских сценариев целиком через публичные интерфейсы приложения. +Регулярное объединение изменений, сопровождаемое автоматической сборкой и проверками. + +### Сквозные тесты (End-to-end tests, E2E) + +Проверки пользовательских сценариев целиком через публичные интерфейсы приложения. ## Версии и релизы - -**Версия (Version)** — определённое состояние продукта, обозначенное номером, например `1.2.1`. +### Версия (Version) + +Определённое состояние продукта, обозначенное номером, например `1.2.1`. + +### Семантическое версионирование (Semantic Versioning, SemVer) + +Правила выбора номера `major.minor.patch` с учётом характера изменений и совместимости. Применение к версиям `0.x` и `1.x` описано в [регламенте релизов](release.md#semver-и-линии-релиза). + +### Релиз (Release) + +Опубликованная версия продукта; её публикация не означает, что она уже установлена в рабочей среде. - -**Семантическое версионирование (Semantic Versioning, SemVer)** — правила выбора номера `major.minor.patch` с учётом характера изменений и совместимости. Применение к версиям `0.x` и `1.x` описано в [регламенте релизов](release.md#semver-и-линии-релиза). +### Выпуск (Release publishing) - -**Релиз (Release)** — опубликованная версия продукта; её публикация не означает, что она уже установлена в рабочей среде. +Публикация подготовленной версии: тега и записи GitHub Release после необходимых проверок и разрешений. Не включает [выкладку](#выкладка-deployment-deploy). - -**Выпуск (Release publishing)** — публикация подготовленной версии: тега и записи GitHub Release после необходимых проверок и разрешений. Не включает [выкладку](#deployment). +### Запись релиза на GitHub (GitHub Release) - -**Запись релиза на GitHub (GitHub Release)** — запись на GitHub, связанная с тегом и содержащая описание версии; к ней могут прилагаться файлы для скачивания. Это не сам тег и не установка приложения. +Запись на GitHub, связанная с тегом и содержащая описание версии; к ней могут прилагаться файлы для скачивания. Это не сам тег и не установка приложения. - -**Фиксация состава релиза (Release cut)** — определение окончательного набора изменений при одобрении PR подготовки релиза. +### Фиксация состава релиза (Release cut) - -**План релиза (Release plan)** — документ с составом версии, рисками и действиями до и после её выпуска и выкладки. +Определение окончательного набора изменений при одобрении PR подготовки релиза. - -**Срочное исправление (Hotfix)** — исправление ошибки в рабочей версии без нарушения совместимости; готовится от тега текущей версии рабочей среды. +### План релиза (Release plan) - -**Патч-релиз (Patch release)** — релиз совместимых исправлений ошибок с увеличением третьего числа версии, например `1.2.0` → `1.2.1`. Такое повышение версии само по себе не означает срочность выпуска. +Документ с составом версии, рисками и действиями до и после её выпуска и выкладки. + +### Срочное исправление (Hotfix) + +Исправление ошибки в рабочей версии без нарушения совместимости; готовится от тега текущей версии рабочей среды. + +### Патч-релиз (Patch release) + +Релиз совместимых исправлений ошибок с увеличением третьего числа версии, например `1.2.0` → `1.2.1`. Такое повышение версии само по себе не означает срочность выпуска. ## Выкладка и рабочая среда - -**Выкладка (Deployment, deploy)** — установка выбранной версии в целевую среду. В этом процессе рабочая среда обновляется по опубликованному тегу, а не по вершине ветки. +### Выкладка (Deployment, deploy) + +Установка выбранной версии в целевую среду. В этом процессе рабочая среда обновляется по опубликованному тегу, а не по вершине ветки. + +### Рабочая среда (Production) - -**Рабочая среда (Production)** — среда, в которой приложение обслуживает реальных пользователей и работает с рабочими данными. +Среда, в которой приложение обслуживает реальных пользователей и работает с рабочими данными. diff --git a/docs/git-workflow/release.md b/docs/git-workflow/release.md index 58bf20a..4b8cce9 100644 --- a/docs/git-workflow/release.md +++ b/docs/git-workflow/release.md @@ -6,7 +6,7 @@ package: prikotov/git-workflow ## Модель релизов -- Для каждого [выпуска](glossary.md#release-publishing) создавайте отдельную `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/TASK-fix-glossary-pure-md-anchors.todo.md b/todo/TASK-fix-glossary-pure-md-anchors.todo.md new file mode 100644 index 0000000..81ef1ad --- /dev/null +++ b/todo/TASK-fix-glossary-pure-md-anchors.todo.md @@ -0,0 +1,87 @@ +--- +type: fix +created: 2026-09-22 00:39:17 (1790037557) +due: +started: 2026-09-22 00:39:30 (1790037570) +completed: +cancelled: +value: V2 +complexity: C1 +priority: P2 +cost_plan: +cost_fact: +depends_on: +epic: +author: Бэкендер Тони (pi) +assignee: Бэкендер Тони (pi) +branch: task/glossary-pure-md-anchors +pr: +status: in_progress +--- + +# TASK-fix-glossary-pure-md-anchors: Глоссарий — чистый Markdown вместо HTML-якорей + +## 0. Простое описание (Human Brief) + +### Проблема простыми словами (Problem) +- Глоссарий использует явные HTML-якоря `` (26 шт.). Валидатор ссылок `prikotov/coding-standard` такие цели не распознаёт (считает только заголовки) и ложно помечает ссылки на термины как битые. +- Владелец экосистемы принял политику чистого Markdown: якоря — только через заголовки, сырой HTML не используем. + +### Варианты или путь решения (Solution Sketch) +- Переделать глоссарий: каждый термин — заголовок H3, определения — обычными абзацами; ссылки на термины заменить на автославки заголовков. + +### Ожидаемый результат (Expected Result) +- В глоссарии нет сырого HTML; все внутренние ссылки пакета проходят `validate-md-links` (v0.33.0) без ложных срабатываний. + +## 1. Концепция и Цель (Concept and Goal) + +### История (User Story) +> **User Story:** Как потребитель пакета, я хочу глоссарий на чистом Markdown с якорями-заголовками, чтобы документация не зависела от сырого HTML и проходила стандартные проверки ссылок. + +### Цель по SMART (Goal) +- Заменить все 26 ``-терминов на H3-заголовки; обновить 3 ссылки на термины (2 внутренних в glossary.md, 1 в release.md); `validate-md-links` на `docs/git-workflow/` — зелёный. + +## 2. Контекст и Границы (Context and Scope) +* **Где делаем:** `docs/git-workflow/glossary.md`, `docs/git-workflow/release.md`. +* **Границы (Out of Scope):** не менять структуру секций глоссария и формулировки определений; не трогать остальные документы. + +## 3. Требования, MoSCoW (Requirements) +### 🔴 Обязательно (Must Have) +- [x] Все термины глоссария — заголовки `###`, определение — абзац с заглавной буквы. +- [x] Ни одного ``/`` в документах пакета. +- [x] Ссылки на термины обновлены на автославки заголовков (`#выкладка-deployment-deploy`, `glossary.md#выпуск-release-publishing`). +- [x] `validate-md-links` (prikotov/coding-standard v0.33.0) на `docs/git-workflow/` — без ошибок. +### ⚫ Won't Have (Не будем делать) +- Поддержку HTML-якорей в валидаторе (отклонена политикой чистого Markdown, PR prikotov/coding-standard#126 закрыт). + +## 4. План реализации (Implementation Plan) +1. [x] Преобразовать 26 терминов глоссария в H3-заголовки скриптом. +2. [x] Обновить ссылки на термины в glossary.md и release.md. +3. [x] Прогнать валидатор ссылок и `composer validate --strict`. + +## 5. Критерии приёмки (Definition of Done) +- [x] `grep -c "` (26 шт.). Валидатор ссылок `prikotov/coding-standard` такие цели не распознаёт (считает только заголовки) и ложно помечает ссылки на термины как битые. -- Владелец экосистемы принял политику чистого Markdown: якоря — только через заголовки, сырой HTML не используем. - -### Варианты или путь решения (Solution Sketch) -- Переделать глоссарий: каждый термин — заголовок H3, определения — обычными абзацами; ссылки на термины заменить на автославки заголовков. - -### Ожидаемый результат (Expected Result) -- В глоссарии нет сырого HTML; все внутренние ссылки пакета проходят `validate-md-links` (v0.33.0) без ложных срабатываний. - -## 1. Концепция и Цель (Concept and Goal) - -### История (User Story) -> **User Story:** Как потребитель пакета, я хочу глоссарий на чистом Markdown с якорями-заголовками, чтобы документация не зависела от сырого HTML и проходила стандартные проверки ссылок. - -### Цель по SMART (Goal) -- Заменить все 26 ``-терминов на H3-заголовки; обновить 3 ссылки на термины (2 внутренних в glossary.md, 1 в release.md); `validate-md-links` на `docs/git-workflow/` — зелёный. - -## 2. Контекст и Границы (Context and Scope) -* **Где делаем:** `docs/git-workflow/glossary.md`, `docs/git-workflow/release.md`. -* **Границы (Out of Scope):** не менять структуру секций глоссария и формулировки определений; не трогать остальные документы. - -## 3. Требования, MoSCoW (Requirements) -### 🔴 Обязательно (Must Have) -- [x] Все термины глоссария — заголовки `###`, определение — абзац с заглавной буквы. -- [x] Ни одного ``/`` в документах пакета. -- [x] Ссылки на термины обновлены на автославки заголовков (`#выкладка-deployment-deploy`, `glossary.md#выпуск-release-publishing`). -- [x] `validate-md-links` (prikotov/coding-standard v0.33.0) на `docs/git-workflow/` — без ошибок. -### ⚫ Won't Have (Не будем делать) -- Поддержку HTML-якорей в валидаторе (отклонена политикой чистого Markdown, PR prikotov/coding-standard#126 закрыт). - -## 4. План реализации (Implementation Plan) -1. [x] Преобразовать 26 терминов глоссария в H3-заголовки скриптом. -2. [x] Обновить ссылки на термины в glossary.md и release.md. -3. [x] Прогнать валидатор ссылок и `composer validate --strict`. - -## 5. Критерии приёмки (Definition of Done) -- [x] `grep -c "` (26 шт.). Валидатор ссылок `prikotov/coding-standard` такие цели не распознаёт (считает только заголовки) и ложно помечает ссылки на термины как битые. +- Владелец экосистемы принял политику чистого Markdown: якоря — только через заголовки, сырой HTML не используем. + +### Варианты или путь решения (Solution Sketch) +- Переделать глоссарий: каждый термин — заголовок H3, определения — обычными абзацами; ссылки на термины заменить на автославки заголовков. + +### Ожидаемый результат (Expected Result) +- В глоссарии нет сырого HTML; все внутренние ссылки пакета проходят `validate-md-links` (v0.33.0) без ложных срабатываний. + +## 1. Концепция и Цель (Concept and Goal) + +### История (User Story) +> **User Story:** Как потребитель пакета, я хочу глоссарий на чистом Markdown с якорями-заголовками, чтобы документация не зависела от сырого HTML и проходила стандартные проверки ссылок. + +### Цель по SMART (Goal) +- Заменить все 26 ``-терминов на H3-заголовки; обновить 3 ссылки на термины (2 внутренних в glossary.md, 1 в release.md); `validate-md-links` на `docs/git-workflow/` — зелёный. + +## 2. Контекст и Границы (Context and Scope) +* **Где делаем:** `docs/git-workflow/glossary.md`, `docs/git-workflow/release.md`. +* **Границы (Out of Scope):** не менять структуру секций глоссария и формулировки определений; не трогать остальные документы. + +## 3. Требования, MoSCoW (Requirements) +### 🔴 Обязательно (Must Have) +- [x] Все термины глоссария — заголовки `###`, определение — абзац с заглавной буквы. +- [x] Ни одного ``/`` в документах пакета. +- [x] Ссылки на термины обновлены на автославки заголовков (`#выкладка-deployment-deploy`, `glossary.md#выпуск-release-publishing`). +- [x] `validate-md-links` (prikotov/coding-standard v0.33.0) на `docs/git-workflow/` — без ошибок. +### ⚫ Won't Have (Не будем делать) +- Поддержку HTML-якорей в валидаторе (отклонена политикой чистого Markdown, PR prikotov/coding-standard#126 закрыт). + +## 4. План реализации (Implementation Plan) +1. [x] Преобразовать 26 терминов глоссария в H3-заголовки скриптом. +2. [x] Обновить ссылки на термины в glossary.md и release.md. +3. [x] Прогнать валидатор ссылок и `composer validate --strict`. + +## 5. Критерии приёмки (Definition of Done) +- [x] `grep -c "