Skip to content

Доработка требований #379

Closed
#380
Closed
Доработка требований#379
#380
@netkeep80

Description

@netkeep80
netkeep80
opened on May 1, 2026

[Requirements] Провести аудит /include и /req, нормализовать требования, ссылки на source anchors и CI-валидацию шаблонов

Контекст

В репозитории уже есть каталог требований req/, PMM-anchor комментарии в include/pmm/** и базовая проверка трассируемости через scripts/check-requirements-traceability.py. Сейчас этого недостаточно для полноценной управляемой модели требований:

  • требования часто сформулированы слишком кратко;
  • часть требований ссылается на исходники текстом вида include/pmm/file.h — анкер anchor-name, а не кликабельной Markdown-ссылкой;
  • проверяется не весь граф трассировки: не хватает строгой проверки входящих/исходящих ссылок, source anchors, обратных ссылок и соответствия требованиям по типу;
  • нет формализованных Markdown-шаблонов требований по типам, аналогичных schema/contract-документации;
  • CI/CD должен блокировать PR, если требования не соответствуют шаблонам или содержат битые ссылки на требования, исходники, тесты или source anchors.

Цель

Сделать полный аудит исходного кода в include/pmm/ и каталога требований req/, привести требования к подробному русскоязычному формату, нормализовать трассировку и расширить CI/CD-проверку так, чтобы каталог требований стал проверяемым и поддерживаемым артефактом проекта.

Область работ

1. Обзор исходного кода в include/pmm/

Необходимо провести структурный обзор всех файлов:

include/pmm/**/*.h
include/pmm/**/*.inc

В обзоре должны быть отражены:

  • публичные API и их ответственность;
  • внутренние подсистемы:
    • address traits;
    • storage backend;
    • block/header/layout model;
    • allocator/free tree;
    • pointer model / pptr;
    • diagnostics/validation/repair;
    • typed API;
    • persistent containers;
    • forest/domain registry;
    • IO helpers;
    • presets/configurations;
  • имеющиеся PMM-anchor комментарии;
  • требования, на которые ссылаются source anchors через req:;
  • участки кода, которые реализуют поведение, но не имеют корректной трассировки на требования;
  • требования, которые ссылаются на исходник, но не имеют обратной req:-аннотации в соответствующем anchor-блоке;
  • дублирующиеся, неиспользуемые или слишком общие anchors.

Результат обзора оформить как отдельный Markdown-документ, например:

docs/include_source_review.md

или, если принято держать аудит рядом с требованиями:

req/00_include_source_review.md

Документ должен быть связан с req/README.md и/или req/13_traceability_matrix.md.

2. Подробный обзор и нормализация требований в req/

Проверить все файлы:

req/01_business_requirements.md
req/02_business_rules.md
req/03_user_requirements.md
req/04_features.md
req/05_functional_requirements.md
req/06_data_requirements.md
req/07_external_interfaces.md
req/08_quality_attributes.md
req/09_constraints.md
req/10_system_requirements.md
req/11_assumptions_dependencies.md
req/12_acceptance_criteria.md
req/13_traceability_matrix.md
req/README.md

Для каждого требования необходимо проверить и исправить:

  • корректность идентификатора;
  • соответствие идентификатора типу требования и файлу;
  • полноту русскоязычного текста требования;
  • наличие контекста/обоснования;
  • корректность приоритета;
  • корректность статуса;
  • корректность исходящих ссылок;
  • корректность входящих ссылок;
  • корректность ссылок на родительские и дочерние требования;
  • корректность ссылок на acceptance criteria;
  • корректность ссылок на tests;
  • корректность ссылок на source anchors в include/pmm/**;
  • отсутствие orphan-требований, orphan-anchors и orphan-tests;
  • отсутствие ссылок на несуществующие требования, файлы и anchors.

3. Исправить ссылки на anchors в исходниках

Сейчас встречается формат:

- `include/pmm/persist_memory_manager.h` — анкер `pmm-persistmemorymanager-load`

Его нужно заменить на кликабельную Markdown-ссылку.

Для ссылок, размещённых из корня репозитория:

[pmm-persistmemorymanager-load](./include/pmm/persist_memory_manager.h#pmm-persistmemorymanager-load)

Для ссылок внутри файлов req/*.md использовать корректный относительный путь от req/:

[pmm-persistmemorymanager-load](../include/pmm/persist_memory_manager.h#pmm-persistmemorymanager-load)

Важно: правило должно быть единым и проверяемым. Если GitHub code view не поддерживает переход по пользовательскому anchor-id внутри .h/.inc, CI всё равно должен проверять семантическое существование PMM-anchor комментария с таким именем в указанном source-файле.

Пример нормализованного блока:

**Реализуется в:**

- [pmm-persistmemorymanager-load](../include/pmm/persist_memory_manager.h#pmm-persistmemorymanager-load)

4. Сделать текст каждого требования подробным и на русском языке

Каждое требование должно быть не одной короткой строкой, а полноценным описанием.

Минимальная структура обычного требования:

## fr-002

**Тип:** functional requirement  
**Название:** Загрузка существующего persistent address space  
**Приоритет:** Must  
**Статус:** Active  
**Источник:** README API, обзор `include/pmm/persist_memory_manager.h`

**Формулировка:**  
Менеджер памяти должен предоставлять операцию загрузки уже существующего persistent address space через публичный API `load(VerifyResult&)`. Операция должна проверять метаданные образа, диагностировать повреждения, восстанавливать служебные индексы там, где это предусмотрено моделью восстановления, и возвращать результат загрузки через `VerifyResult`.

**Контекст и обоснование:**  
Загрузка является ключевым сценарием использования PMM, поскольку библиотека управляет persistent address space, который должен переживать завершение процесса и последующую загрузку по другому runtime-адресу.

**Реализует:**

- [ur-005](03_user_requirements.md#ur-005)
- [feat-001](04_features.md#feat-001)
- [feat-004](04_features.md#feat-004)

**Реализуется в:**

- [pmm-persistmemorymanager-load](../include/pmm/persist_memory_manager.h#pmm-persistmemorymanager-load)

**Проверяется в:**

- [ac-006](12_acceptance_criteria.md#ac-006)

**Примечания:**  
`verify()` должен оставаться read-only диагностикой, а `load(VerifyResult&)` может выполнять документированное восстановление служебных структур.

5. Разработать Markdown-шаблоны требований по типам

Добавить каталог шаблонов:

req/templates/
  README.md
  business_requirement.md
  business_rule.md
  user_requirement.md
  feature.md
  functional_requirement.md
  data_requirement.md
  external_interface.md
  quality_attribute.md
  constraint.md
  system_requirement.md
  assumption.md
  dependency.md
  acceptance_criterion.md

Шаблоны должны быть именно Markdown-контрактами, а не JSON Schema, но по смыслу должны работать как schema:

  • указывать обязательные поля;
  • указывать допустимые значения;
  • указывать правила ссылок;
  • указывать правила формулировки;
  • давать пример корректного требования;
  • давать пример некорректного требования;
  • описывать, какие блоки разрешены/запрещены для данного типа.

Общие обязательные поля для большинства требований

## <id>

**Тип:** <type>
**Название:** <short Russian name>
**Приоритет:** Must | Should | Could | Won't
**Статус:** Draft | Active | Deprecated | Recovered | Superseded
**Источник:** <source>

**Формулировка:**  
<подробный русский текст требования>

**Контекст и обоснование:**  
<почему требование существует>

**Реализует:**  
<ссылки на родительские требования или `—`, если неприменимо>

**Реализуется в:**  
<ссылки на дочерние требования, source anchors или `—`, если неприменимо>

**Проверяется в:**  
<acceptance criteria / tests или `—`, если неприменимо>

**Примечания:**  
<опционально>

Специфика по типам

br — business requirement

Обязательные смысловые поля:

  • бизнес-цель;
  • ожидаемая ценность;
  • границы;
  • связь с user requirements/features.
rule — business rule

Обязательные смысловые поля:

  • правило;
  • область применения;
  • запрещённые состояния;
  • последствия нарушения;
  • связанные functional/data/system requirements.
ur — user requirement

Обязательные смысловые поля:

  • роль пользователя;
  • пользовательская цель;
  • сценарий;
  • ожидаемый результат;
  • связь с features / acceptance criteria.
feat — feature

Обязательные смысловые поля:

  • описание возможности;
  • пользовательский или системный эффект;
  • включённое поведение;
  • явно исключённое поведение;
  • связь с FR/QA/AC.
fr — functional requirement

Обязательные смысловые поля:

  • триггер/условие;
  • поведение системы;
  • результат;
  • ошибки/отказы;
  • source anchors;
  • acceptance criteria.
dr — data requirement

Обязательные смысловые поля:

  • структура данных;
  • инварианты;
  • lifetime/persistence;
  • допустимые значения;
  • связь с layout/storage/validation code.
if — external interface

Обязательные смысловые поля:

  • внешний API/интерфейс;
  • сигнатуры или contract-level описание;
  • preconditions;
  • postconditions;
  • ошибки;
  • compatibility notes.
qa — quality attribute

Обязательные смысловые поля:

  • атрибут качества;
  • измеримая характеристика;
  • сценарий проверки;
  • допустимый порог или качественный критерий;
  • связанное функциональное поведение.
con — constraint

Обязательные смысловые поля:

  • ограничение;
  • причина ограничения;
  • область действия;
  • последствия для реализации;
  • связанные требования.
sys — system requirement

Обязательные смысловые поля:

  • системный аспект;
  • runtime/build-time условия;
  • зависимости от платформы/компилятора;
  • связь с CI/test matrix.
asm — assumption

Обязательные смысловые поля:

  • предположение;
  • где оно используется;
  • риск при нарушении;
  • fallback/mitigation, если есть.
dep — dependency

Обязательные смысловые поля:

  • зависимость;
  • тип зависимости;
  • версия/условие;
  • влияние на build/runtime;
  • fallback/mitigation, если есть.
ac — acceptance criterion

Обязательные смысловые поля:

  • проверяемое поведение;
  • шаги или сценарий проверки;
  • expected result;
  • ссылки на требования, которые критерий проверяет;
  • ссылки на tests, если есть.

6. Реализовать CI/CD-проверку требований

Расширить scripts/check-requirements-traceability.py или добавить новый скрипт:

scripts/check-requirements-catalog.py

CI должен запускать его в Docs Consistency workflow при изменениях:

req/**
include/pmm/**
tests/**
scripts/check-requirements-*.py
.github/workflows/docs-consistency.yml

6.1. Структура требований

CI должен проверять:

  • каждый ## <id> имеет валидный id;
  • id соответствует типу и файлу;
  • все обязательные поля присутствуют;
  • поля идут в допустимом порядке или распознаются независимо от порядка;
  • Тип соответствует префиксу id;
  • Приоритет входит в разрешённый enum;
  • Статус входит в разрешённый enum;
  • текст Формулировка не пустой и написан на русском языке;
  • требование не состоит только из одной короткой строки;
  • для каждого типа применяются свои обязательные поля из req/templates/*.md.

6.2. Исходящие ссылки

Проверить все ссылки из каждого требования:

  • ссылки на другие требования;
  • ссылки на source anchors в include/pmm/**;
  • ссылки на tests;
  • ссылки на docs;
  • ссылки на acceptance criteria;
  • ссылки на traceability matrix.

Любая ссылка должна вести на существующий файл и существующий anchor, если указан #anchor.

6.3. Входящие ссылки

Для каждого требования построить reverse index и проверить:

  • каждое требование, кроме допустимых top-level требований, имеет хотя бы одну входящую ссылку;
  • каждое requirement id, указанное в req: source annotation, существует;
  • каждый source anchor, на который ссылается требование, содержит обратную req:<id> аннотацию;
  • каждая acceptance criterion имеет ссылку на проверяемое требование;
  • каждое Must/Should functional requirement имеет хотя бы один acceptance criterion или тест, если для него явно не задано исключение.

6.4. Source anchors

Для include/pmm/**/*.h и include/pmm/**/*.inc проверить:

  • формат anchor-комментария;
  • уникальность anchor id в пределах репозитория;
  • валидный slug anchor name;
  • наличие хотя бы одной req: ссылки, если anchor участвует в трассировке;
  • все req: ссылки указывают на существующие требования;
  • anchor, указанный в req/*.md, реально существует в указанном файле;
  • недопустимы ссылки вида `file` — анкер `anchor` без Markdown-link.

6.5. Tests traceability

Для tests/**/*.cpp проверить:

  • все req: ссылки указывают на существующие требования или acceptance criteria;
  • если тест указан в Проверяется в: или Тесты:, файл существует;
  • если test anchor указан как проверка требования, соответствующий test file содержит обратную req: ссылку;
  • acceptance criteria не должны ссылаться на несуществующие тесты.

6.6. Traceability matrix

Проверить и обновить req/13_traceability_matrix.md:

  • все требования присутствуют в матрице;
  • все source anchors, tests и AC отражены;
  • нет строк с несуществующими требованиями;
  • нет устаревших ссылок после переименования anchors;
  • матрица может генерироваться автоматически или проверяться как hand-maintained artifact, но правило должно быть явно описано в req/README.md.

7. Обновить документацию

Обновить:

req/README.md
req/13_traceability_matrix.md
docs/include_source_review.md или req/00_include_source_review.md

В req/README.md описать:

  • типы требований;
  • формат id;
  • обязательные поля;
  • правила ссылок;
  • правила source anchors;
  • правила обратной трассировки;
  • команды локальной проверки;
  • как добавлять новое требование;
  • как добавлять новый source anchor;
  • как добавлять новый acceptance criterion;
  • как обновлять traceability matrix.

Acceptance Criteria

Issue считается выполненной, если:

  • Выполнен обзор всех файлов include/pmm/**/*.h и include/pmm/**/*.inc.

  • Результат обзора сохранён в Markdown-документе и связан с каталогом требований.

  • Все требования в req/*.md приведены к подробному русскоязычному формату.

  • Для каждого требования проверены и исправлены исходящие ссылки.

  • Для каждого требования проверены и исправлены входящие ссылки.

  • Все ссылки вида `include/pmm/file.h` — анкер `anchor` заменены на Markdown-ссылки.

  • Все ссылки на source anchors указывают на существующие PMM anchors.

  • Все source anchors, на которые есть ссылки из требований, содержат обратные req: ссылки.

  • Все req: ссылки в include/pmm/** и tests/** указывают на существующие требования.

  • Созданы Markdown-шаблоны требований по типам в req/templates/.

  • CI/CD проверяет соответствие каждого требования шаблону его типа.

  • CI/CD проверяет существование файлов и anchors во всех Markdown-ссылках.

  • CI/CD проверяет входящую и исходящую трассировку.

  • CI/CD падает на битых ссылках, отсутствующих обязательных полях, невалидных id и orphan anchors.

  • req/README.md обновлён и описывает новые правила.

  • req/13_traceability_matrix.md обновлена или генерируется/проверяется автоматически.

  • Локально проходит:

    python3 scripts/check-requirements-traceability.py

  • Локально проходит новая или расширенная проверка:

    python3 scripts/check-requirements-catalog.py

    либо эквивалентная команда, если проверка реализована внутри существующего скрипта.

  • Workflow Docs Consistency запускает новую проверку на PR и push.

Предлагаемый порядок выполнения

  1. Зафиксировать текущую карту req id -> source/test/doc links.
  2. Зафиксировать текущую карту source anchor -> req ids.
  3. Провести обзор include/pmm/**.
  4. Спроектировать Markdown-шаблоны требований.
  5. Нормализовать требования по типам.
  6. Исправить ссылки на source anchors.
  7. Реализовать расширенную CI/CD-валидацию.
  8. Обновить req/README.md.
  9. Обновить или сгенерировать req/13_traceability_matrix.md.
  10. Прогнать локальные проверки и CI.

Технические замечания

  • Парсер требований лучше делать не только regex-based, а как минимум секционным Markdown parser'ом: ## id открывает requirement block, дальше валидируются поля внутри блока.
  • Для source anchors нужно строить отдельный индекс по include/pmm/**/*.h и include/pmm/**/*.inc.
  • Для тестов нужно строить отдельный индекс по tests/**/*.cpp.
  • Для Markdown-ссылок нужно проверять:
    • существование файла;
    • существование heading anchor в .md;
    • существование PMM source anchor в .h/.inc;
    • существование line/test file references, если они используются.
  • Для ссылок из req/*.md в include/pmm/** относительный путь должен учитывать, что файл находится внутри req/, то есть предпочтительно использовать ../include/pmm/....
  • Если часть требований осознанно не имеет реализации или теста, это должно быть явно выражено полем Статус, Примечания или отдельным allowlist-файлом, а не молчаливым пропуском проверки.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions