03. Версионирование носителя — V1–V6¶
Часть RENAR Standard v1.0-draft · ← Оглавление
3.1 Шесть возможностей носителя¶
Инверсия источника истины из главы 2 — побеждает требование, а не код — держится на одном физическом условии: носитель обязан честно помнить, что и когда менялось. Если прошлое состояние можно переписать задним числом, фраза «реализация прошла приёмку против требований версии X» теряет смысл, а вместе с ней рушится весь договор о приёмке. Поэтому шесть возможностей V1–V6 — не инфраструктурная деталь, а фундамент, на котором идея RENAR вообще стоит; их и выносим вперёд, до глав об артефактах.
Глава даёт детальную нормативную формулировку каждой возможности: предусловия, постусловия, связь с цепочкой источника истины и примеры отображения на распространённые носители. Концептуальное обоснование — §2.5 (утверждение 3 «Положения в типологии методологий»).
Конкретный механизм версионирования — распределённый или централизованный VCS, document store с разрешением конфликтов — взаимозаменяем. RENAR нормирует возможности, а не инструменты.
3.2 Обоснование обязательности¶
Разберём по одной, что именно ломается без каждой возможности. Связь здесь структурная, а не операционная: дело не в дисциплине команды, а в том, что без возможности соответствующее свойство истины просто нечем выразить.
| Нет возможности | Что становится невозможным | Связь в RENAR |
|---|---|---|
| V1 (неизменяемая история) | «Реализация собрана против требований по состоянию на дату X» | происхождение, журнал аудита, гейт приёмки |
| V2 (атомарная единица изменения) | Гарантированная согласованность изменений | delta-ADAPT как атомарная единица изменения (см. §7.6) |
| V3 (сравнение различий и рецензирование) | Утверждение требований и спецификаций | QG QG-ADAPT-approve, QG-spec-approved |
| V4 (ветвление / набор изменений) | Черновик отделим от утверждённой правды | переходы draft → review → approved |
| V5 (сквозная фиксация версии) | Привязка версии требования из реализации | поле verifies[].requirement-version в TC (§9) |
| V6 (автор и отметка времени) | происхождение каждого изменения | подписи в ADAPT, ai-provenance в SR/SPEC |
Поэтому носитель без V1–V6 — плоский файловый сервер без истории, document store без разрешения конфликтов, любой механизм без неизменяемого отслеживания изменений — не реализует RENAR независимо от прочих достоинств. Это структурное ограничение, а не вопрос дисциплины команды.
3.3 Нормативные определения V1–V6¶
Параграфы §3.3.1–§3.3.6 сформулированы независимо от конкретного носителя. Имена конкретных продуктов — только в §3.4 (пример) и §3.6 (иллюстрации языка).
3.3.1 V1 — неизменяемая история¶
Возможность (immutable history): носитель обязан обеспечить, что для любого артефакта любое прошлое состояние адресуемо и восстановимо без потерь.
Предусловия: артефакт зарегистрирован в носителе как объект версионирования.
Постусловия: для любого момента времени T в истории артефакта существует стабильный идентификатор версии, через который состояние на момент T полностью восстанавливается.
Без V1 невозможно:
- Восстановить состояние артефакта на дату подписания контракта.
- Сравнить текущее состояние с опорным.
- Построить журнал аудита для соответствия (глава 13 §13.4).
- Задать базовую точку для delta-ADAPT.
Конкретные реализации на разных носителях — §3.4.
3.3.2 V2 — атомарная единица изменения¶
Возможность (atomic change unit): носитель обязан обеспечить, что любое изменение артефакта (или согласованной группы артефактов) фиксируется как одна транзакция: всё или ничего. Промежуточные несогласованные состояния снаружи не наблюдаемы.
Предусловия: у носителя есть понятие транзакции (atomic change).
Постусловия: после атомарного изменения либо все правки видны наблюдателю, либо ни одна. Промежуточное «рассогласованное» состояние недопустимо.
Без V2 невозможно:
- Согласованно обновить BR и связанные SR одной транзакцией.
- Гарантировать согласованность требования и метаданных
linked-tasks[]. - Оформить утверждение ADAPT как единое атомарное действие (двойная подпись + переход
client-ready → approvedза одну транзакцию). - Откатить изменение без «полуприменённого» состояния.
3.3.3 V3 — сравнение различий и рецензирование¶
Возможность (diff & review): носитель обязан обеспечить, что предложенное (но ещё не интегрированное) изменение представимо как diff против опорного состояния, и человек или AI-агент с правом рецензирования может одобрить или отклонить его до включения в утверждённую правду.
Предусловия: предложенное изменение существует отдельно от утверждённой правды (см. V4).
Постусловия: до утверждения изменение существует, но не считается частью источника истины. После утверждения становится частью источника истины как атомарная единица изменения (V2).
Без V3 невозможно:
- Quality gates QG-ADAPT-approve, QG-spec-approved, QG-sr-approved (см. глава 10).
- Двойная подпись ADAPT (см. §7.5).
- Независимое рецензирование кода и спецификации (см. §2.3.3 (2)).
- Состязательный обзор как гейт.
3.3.4 V4 — ветвление / набор изменений¶
Возможность (branching / change-set): носитель обязан разделить работу в процессе (WIP) и утверждённую правду (источник истины) так, что несколько независимых изменений могут разрабатываться параллельно без влияния на источник истины.
Предусловия: артефакт зарегистрирован в носителе.
Постусловия: для любого артефакта в данный момент могут существовать (a) ровно одна утверждённая версия (источник истины) и (b) ноль или более черновиков — каждый либо интегрируется через V3, либо отклоняется.
Без V4 невозможно:
- Отделить статус жизненного цикла
draftотapproved(глава 10). - Параллельно вести несколько delta-ADAPT.
- Держать backward findings в
asked-to-clientбез блокировки утверждённой правды. - Эволюционировать SPEC-* экспериментально без влияния на требования, производные от реализации.
3.3.5 V5 — сквозная фиксация версии между носителями¶
Возможность (cross-substrate version pin): носитель A, использующий артефакт носителя B, обязан иметь возможность зафиксировать конкретную версию артефакта носителя B как стабильный сквозной идентификатор. Этот идентификатор должен однозначно восстанавливать состояние артефакта в носителе B.
Предусловия: носитель A и носитель B удовлетворяют V1 (у каждого есть стабильный идентификатор версии).
Постусловия: для каждой зафиксированной ссылки в носителе A на артефакт носителя B существует пара (artifact-id, version-id), и по ней восстанавливается полное состояние артефакта носителя B на момент фиксации.
Без V5 невозможно:
- Поле
verifies[].requirement-versionв TC (глава 9 §9.4). - Привязать носитель реализации (код) к конкретной версии носителя требований (SR/SPEC).
- Гарантировать: «эта реализация прошла приёмку против требований версии X».
- Метрика свежести TC (зафиксированная версия старше текущей — TC устарел).
3.3.6 V6 — автор и отметка времени¶
Возможность (author + timestamp): носитель обязан для каждой атомарной единицы изменения (V2) зарегистрировать идентифицируемого автора (человек или AI-агент с уникальным id) и отметку времени с точностью не хуже секунды.
Предусловия: у носителя есть система идентификации авторов.
Постусловия: для любой атомарной единицы изменения запрос «кто? когда?» даёт однозначный ответ.
Без V6 невозможно:
- Двойная подпись ADAPT (подпись = автор + отметка времени в нативной для носителя форме).
ai-provenanceво frontmatter артефактов.- Журнал аудита для соответствия.
- Метрика состязательно-найденного (распределение backward findings по авторам).
3.4 Отображение V1–V6 на конкретные носители (пример)¶
Информативно. Таблица показывает, как V1–V6 обычно реализуются на распространённых носителях. Она не часть нормативного контракта. Любой носитель, удовлетворяющий V1–V6, реализует главу 3 — независимо от того, есть ли он в таблице.
| Возможность | Git | Mercurial | SVN | Perforce | Document store (пример) |
|---|---|---|---|---|---|
| V1 — неизменяемая история | commits, hash-chain | changesets, hash-chain | revisions, sequential numbering | changelists | revision tree per doc (_rev) |
| V2 — атомарная единица изменения | commit | commit | atomic revision | changelist submit | document update (single _rev advance) |
| V3 — diff и рецензирование | merge request / pull request | hg phabricator, mq | svn diff + commit gate | swarm review | API workflow + Hub UI approval |
| V4 — ветвление / набор изменений | branches | named branches, bookmarks | branches (copy semantic) | branches / streams | conflict branches / WIP docs / draft status |
| V5 — сквозная фиксация версии | submodule SHA | subrepo changeset | externals (peg rev) | branches / streams reference | _rev reference + created_by_order |
| V6 — автор и отметка времени | commit metadata | commit metadata | revision properties | changelist metadata | doc fields (author, updated_at) |
Практические workflow для каждого носителя:
3.5 Носитель, не удовлетворяющий V1–V6¶
Следующие конфигурации не реализуют RENAR, потому что нарушают одну или более возможностей:
| Конфигурация | Нарушение |
|---|---|
| Плоский файловый сервер; «версия» = переименование файла | V1 (нет стабильной истории; переименование = потеря происхождения) |
| Document store без разрешения конфликтов | V2 (возможно рассогласованное состояние) |
| Wiki без истории ревизий | V1, V6 |
| Wiki с историей ревизий, но без процедуры утверждения | V3 |
VCS с mtime вместо неизменяемого идентификатора |
V1, V5 |
| носитель с правкой исторических ревизий на месте | V1 (история изменяема — журнал аудита невозможен) |
Команда, внедряющая RENAR на носителе из этого списка, должна либо перейти на подходящий носитель, либо построить компенсирующий слой, обеспечивающий V1–V6 поверх базового хранения. В обоих случаях манифест соответствия обязан явно документировать, как реализованы V1–V6.
3.6 Язык, независимый от конкретного носителя¶
Нормативные параграфы RENAR используют независимые от носителя формулировки: «атомарная единица изменения» (V2), «фиксация версии» (V5), состояние approved (после V3), «черновик» (V4). Термины, специфичные для носителя (имена инструментов и их примитивы), допустимы только:
- в иллюстративных таблицах с явной пометкой (как §3.4);
- в перекрёстных ссылках на guide/ по конкретному носителю;
- в приложениях к нормативным главам.
3.6.1 Примеры: нормативная форма и иллюстрация на git¶
| Нормативная (независимая от носителя) формулировка | Иллюстрация на git (не норма) |
|---|---|
| «Изменение требования регистрируется как атомарная единица изменения с автором и временем (V2, V6)» | «Изменение регистрируется как commit» |
| «Изменение проходит сравнение различий и рецензирование до интеграции (V3)» | «Изменение проходит review merge request до merge в main» |
| «носитель реализации фиксирует конкретную версию носителя требований (V5)» | «.src фиксирует submodule SHA .req» |
| «Двойная подпись ADAPT — два независимых события автор+отметка времени (V6)» | «Двойная подпись — два approve в UI merge request» |
| «Правка уже утверждённого требования вне атомарной единицы изменения с рецензированием — нарушение» | «Force-push на approved branch блокируется hooks» |
3.6.2 Носитель как параметр соответствия¶
Каждая команда фиксирует выбор носителя в манифест соответствия с явным отображением V1–V6 → нативные для носителя примитивы. При смене носителя (например, с git на document store) манифест обновляют и проводят регрессионную проверку V1–V6 (§3.8).
3.7 Манифест соответствия¶
Каноническая схема — §13.4, файл RENAR-CONFORMANCE.yaml (YAML 1.2) в корне носителя требований. Глава 3 нормирует часть, относящуюся к носителю: декларацию выбранного носителя и отображение V1–V6 (поле substrate-capabilities, §13.4.2).
# Фрагмент RENAR-CONFORMANCE.yaml — substrate-специфичная часть
# (полная схема — §13.4.2)
substrate:
requirements: { tool: "<name>", version: "<version>" }
implementation: { tool: "<name>", version: "<version>" }
v1-v6-mapping:
v1-immutable-history: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v2-atomic-change-unit: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v3-diff-review: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v4-branching: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v5-cross-substrate-pin: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v6-author-timestamp: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
Подтверждение обязательных положений (§2.3 инверсия источника истины, §7 ADAPT, §8 закрытый список 9 типов SPEC, §9 pos/neg и др.) — в поле mandatory-clauses-confirmed (§13.3–§13.4).
Манифест обязателен для любого заявления о соответствии уровня RENAR-1 и выше (глава 13).
3.8 Миграция носителя¶
При смене носителя команда обязана выполнить шаги по порядку:
- Аудит до миграции: целевой носитель удовлетворяет V1–V6; иначе миграция запрещена до компенсирующего слоя.
- Черновик манифеста: обновлённый
RENAR-CONFORMANCE.yamlс новым отображением. - Проверка изоморфности: все артефакты (BR, SR, SPEC, ADAPT, TC) переносимы без потери полей, id и происхождения. Все id неизменяемы — переименование при миграции запрещено.
- Атомарное переключение: миграция — атомарная единица изменения на уровне процесса; одномоментный перевод всех артефактов. Параллельное использование двух носителей как источника истины запрещено (см. §2.3.3 (1)).
- Проверка после миграции: регрессионная проверка V1–V6 на реальных артефактах.
- Регистрация манифеста: обновлённый
RENAR-CONFORMANCE.yamlрегистрируется в новом носителе как атомарная единица изменения (V2).
После переключения старый носитель — архив (снимок только для чтения) или упразднён. Параллельная работа на двух носителях как источника истины запрещена.
3.9 Связь с другими главами¶
| Глава | Связь |
|---|---|
| 02 Положение в типологии §2.5 | Концептуальное обоснование V1–V6 |
| 06 Иерархия требований | frontmatter опирается на V1 (неизменяемый id), V5 (фиксация версии) |
| 07 ADAPT | Утверждение двойной подписью — V3 + V6; delta-ADAPT — V1 + V2 + V4 |
| 08 Спецификации | constrained-by[], depends-on[], referenced-by[] — через V5 |
| 09 Тест-кейсы | verifies[].requirement-version — прямое применение V5 |
| 10 Жизненный цикл и QG | Переходы статусов — V2 + V3 + V4 |
| 11 Модель зрелости | RENAR-3+: V5 обязателен; RENAR-4+: V6 + ai-provenance |
| 13 Соответствие | RENAR-CONFORMANCE.yaml — обязательный артефакт |
| guide/03 | Практика на git |
| guide/04 | Практика на document store |