SPECIFICATION

Глава 10. Управление версиями

Декларация единственного авторитетного источника (Single Source of Truth). Политика управления версиями DTP определяется главой 1 §1.7 «Управление версиями и совместимость» как единственный авторитетный источник. Настоящая глава MUST NOT переопределять политику, уже установленную в §1.7; настоящая глава предоставляет только операционные механизмы правил §1.7 (привязка к проводному формату, конкретные полезные нагрузки кодов ошибок, последовательность согласования, шаблон декларации реализации) и поток управления (соглашения о каталогах и статусах, действия финализации). Всякий раз, когда какое-либо утверждение настоящей главы неоднозначно по отношению к §1.7, §1.7 MUST иметь приоритет.

10.1 Формат номера версии (операционная отсылка)

Семантика номера версии протокола DTP, двухуровневая структура MAJOR.MINOR (без PATCH), правило классификации изменений и определения ортогональных осей находятся в §1.7.1 и §1.7.2 и здесь не повторяются.

Привязка к проводному формату: заголовок каждого LogicalFrame MUST содержать полное поле ProtocolVersion (см. раздел 4.4):

interface ProtocolVersion {
  major: number;  // неотрицательное целое число
  minor: number;  // неотрицательное целое число
}

Начальная версия протокола, определённая настоящей спецификацией, MUST быть { major: 1, minor: 0 } (то есть dtp/1.0).

10.2 Матрица совместимости версий (операционное дополнение к §1.7.3)

Нормативные правила совместимости и согласования находятся в §1.7.3. Приведённая ниже таблица является их операционной реализацией на уровне обработки фреймов и MUST читаться согласно §1.7.3; при неоднозначности приоритет имеет §1.7.3.

Версия полученного фреймаОбработка
Равна наивысшей версии получателяОбработать в обычном режиме
Равна предыдущей мажорной версии наивысшей версии получателя (major - 1)Обработка совместимости (обработать в соответствии с более старой спецификацией)
Выше наивысшей версии получателяMUST вернуть VERSION_INCOMPATIBLE (7001)
Мажорная версия ниже (наивысшая версия получателя - 1)MUST вернуть VERSION_INCOMPATIBLE (7001)
Та же мажорная версия, более низкая минорная версияОбработать в обычном режиме (обратно совместимая)
Та же мажорная версия, более высокая минорная версияSHOULD обработать (игнорировать нераспознанные необязательные поля)

10.2.1 Толерантность к минорным версиям (операционная реализация §1.7.3)

При получении фрейма с той же мажорной версией, но более высокой минорной версией реализация MUST:

  1. Обработать известные поля;
  2. SHOULD игнорировать неизвестные необязательные поля;
  3. MUST NOT отвергать весь фрейм из-за неизвестных необязательных полей;
  4. MUST NOT генерировать ошибку.

10.3 Обработка несовместимости версий (операционный механизм)

10.3.1 Обработка на стороне получателя

Когда получатель получает LogicalFrame, версия протокола которого выше, чем поддерживаемая им (и выходит за пределы диапазона совместимости), он MUST:

  1. Не обрабатывать фрейм;
  2. Отправить отправителю ошибку VERSION_INCOMPATIBLE (7001);
  3. Включить наивысшую поддерживаемую им версию в поле details уведомления об ошибке:
{
  errorCode: 7001,
  errorMessage: "Protocol version higher than supported",
  details: {
    supportedMaxVersion: { major: 1, minor: 0 }
  }
}

Семантика кода ошибки 7001 регулируется таблицей кодов ошибок главы 9 и schema; настоящая глава её не переопределяет.

10.3.2 Обработка на стороне отправителя

После получения ошибки VERSION_INCOMPATIBLE отправитель MAY выбрать:

  1. Понизить версию до поддерживаемой пиром и повторно отправить фрейм (SHOULD иметь приоритет при условии существования общего MAJOR; без понижения через MAJOR, см. §1.7.3);
  2. Уведомить приложение верхнего уровня о несовместимости версий и MUST NOT автоматически повторять попытки бесконечно.

Реализация MUST NOT немедленно закрывать Session после получения ошибки несовместимости версий и SHOULD предоставить возможность для понижения версии.

10.3.3 Согласованность версии в пределах сессии и последовательность согласования

При установлении DTP-сессии обе стороны MUST согласовать единую версию протокола (правила согласования в §1.7.3). В течение сессии:

  1. Согласованная версия MUST использоваться на протяжении всей сессии;
  2. MUST NOT переключать версии протокола в середине сессии.

Согласование версий SHOULD следовать данной последовательности; конкретный носитель (расширения CAP, первый Request_Frame/Response_Frame и т.д.) MAY выбираться реализацией, но согласование MUST быть завершено до отправки первого data-фрейма:

DTP_A                              DTP_B
  |                                   |
  |-- Hello (supported_versions) --->|
  |                                   |
  |<-- Hello_Ack (chosen_version) ---|
  |                                   |
  |    [both sides use chosen_version]|

10.4 Эволюция протокола и управление

Настоящий раздел предоставляет операционный поток правил управления §1.7. Упоминаемые здесь формат git tag, перечисление статусов документа и определение редакционной редакции MUST быть привязаны к §1.7; настоящий раздел их не переопределяет.

10.4.1 Соглашения о каталогах и статусах (согласованные с Faying Protocol)

  • Статус документа является маркером front matter и MUST NOT кодироваться в пути (см. §1.7.1).
  • Под specification/ MUST сохраняться ровно одна изменяемая рабочая область draft/ (с непрерывным обновлением).
  • Все каталоги, кроме draft/, MUST именоваться по дате публикации (например, 2025-10-25/), представляя замороженную опубликованную редакцию; «не draft означает опубликовано».
  • Является ли опубликованная редакция в настоящее время Final, Deprecated или Obsolete, определяется исключительно полем status её файлов и MUST NOT выводиться из имени каталога.
  • Создание каталогов, именованных по статусу (например, final/), ЗАПРЕЩЕНО — иначе устаревание редакции потребовало бы перемещения каталогов и нарушения ссылок.
  • WHEN происходит переход статуса, только поле status во front matter MUST изменяться, и каталоги MUST NOT перемещаться.

10.4.2 Черновые и официальные версии

  • Черновик: документы находятся в docs/{lang}/specification/draft/, schema в schema/draft/; номера черновых версий MAY использовать { major: 0, minor: N }. В период Draft НЕТ обещания совместимости (см. §1.7.5), и черновики MUST NOT использоваться в продакшене.
  • Официальная версия: MUST пройти полное рецензирование и публичное обсуждение и иметь неизменяемый снимок версии; документы находятся в docs/{lang}/specification/{YYYY-MM-DD}/, schema в schema/{YYYY-MM-DD}/. Первая официальная версия — 2025-10-25, соответствующая версии протокола dtp/1.0.
  • Неизменяемость снимка версии: после выпуска официальной версии она MUST оставаться неизменяемой; чисто текстовые errata размещаются в новом каталоге даты публикации согласно §1.7.4 при замороженных существующих каталогах, и содержимое спецификации или schema опубликованного снимка MUST NOT переписываться на месте.

10.4.3 Стандартные действия финализации (Draft → Final)

WHEN выполняется финализация, Doc Governance Process MUST последовательно выполнить следующие действия:

  1. С помощью git mv перенести все файлы из draft/ в каталог даты публикации (имена файлов без изменений) и очистить draft/;
  2. По каждому файлу изменить status с Draft на Final;
  3. Зафиксировать date на официальную дату публикации, заблокировать editors на список подписантов финализации и сохранить version без изменений;
  4. Записать цепочку истории replaces (указывающую на черновой каталог и короткий хеш коммита финализации) во front matter README;
  5. Поставить тег dtp-v<MAJOR.MINOR>-final, который MUST покрывать тело + тестовые векторы + schema вместе;
  6. Когда задействованы несколько языков / файлов, они MUST переноситься вместе в одном коммите; односторонний выпуск запрещён.

10.4.4 Устаревание и удаление

Реализация SHOULD делать функциональность устаревшей через следующий процесс:

  1. Пометить как устаревшее: пометить функциональность как устаревшую в версии MINOR, но MUST продолжать её поддерживать;
  2. Переходный период: как минимум один полный цикл версии MAJOR;
  3. Удаление: удалить в следующей версии MAJOR.

Реализация MUST NOT удалять устаревшую функциональность в версии MINOR.

10.5 Декларация реализации

Реализация DTP MUST объявить в своей документации:

  1. Наивысшую поддерживаемую версию протокола;
  2. Все поддерживаемые предыдущие мажорные версии;
  3. Поддерживается ли прямая совместимость (обработка фреймов с более высокими минорными версиями);
  4. Расширения, определяемые реализацией, если таковые имеются.

Например:

Декларация версии реализации DTP X:

  • Наивысшая поддерживаемая версия протокола: 1.0
  • Совместимые предыдущие версии: нет (первая официальная версия)
  • Прямая совместимость: поддерживается; игнорирует неизвестные необязательные поля
  • Алгоритмы шифрования: AES-256-GCM, ChaCha20-Poly1305
  • Транспортные адаптеры: BLE, WebSocket, TCP