Версия движка и заметки о выпусках

Корневой VERSION задаёт идентификатор движка. Эта политика CalVer с календарным годом, ADR-0002 и процедура изменения контрактов обязательны для каждого обновления master. Перед обновлением игры прочитайте историю изменений.

Нотация

Логические поля — YEAR.MAJOR.MINOR.PATCH. YEAR — четырёхзначный год по UTC. MAJOR — положительный номер релизной линии внутри года, начиная с 1; это не месяц и не обещание совместимости SemVer. MINOR считает опубликованные изменения master внутри линии. PATCH используется только в релизной ветке. Числа записываются без ведущих нулей; minor и patch начинаются с 0.

VERSION содержит ровно один идентификатор и необязательный перевод строки. В master всегда три числовых поля и -dev; в релизной ветке — четыре поля и либо -rc, либо отсутствие суффикса. Нумерованных rc, alpha, beta, времени сборки и Git-суффиксов нет. Неизменяемые Git-теги имеют вид v<version>.

Календарный месяц записывается в дате изменения/выпуска по UTC, а не в MAJOR. При подготовке обновления master выставляйте актуальный год UTC. Первое обновление нового года начинает YEAR.1.0-dev; иначе minor увеличивается ровно на один. После одобренного владельцем среза увеличьте major на один и сбросьте minor в ноль. Год, major и minor среза релизной ветки не меняются: патч, выпущенный в следующем календарном году, сохраняет идентификатор среза.

Каждое обновление master

Одно опубликованное изменение — один коммит в цепочке первого родителя master, включая merge, правки только документации, тесты, CI, зависимости и отмены изменений. Каждый шаг получает новый minor и отдельную датированную заметку на двух языках. Исправляющие коммиты рабочей ветки не являются отдельными обновлениями master; перед интеграцией согласуйте итоговое изменение с последним master. При прямом push нескольких коммитов правило выполняется на каждом шаге цепочки первого родителя. Параллельные изменения должны влить последний опубликованный tip обычным merge и пересчитать следующий номер перед публикацией; опубликованную историю переписывать нельзя.

1. Запишите точные исходную и целевую ревизии, проверьте весь диапазон исходников/тестов/документации и перечислите затронутые поверхности и инварианты смысла существующих значений.
2. Сохраните смысл всех существующих допустимых входов. Добавление/расширение сохраняет старые случаи; замена получает отдельное имя, тип, ключ или явную границу формата, а прежний API удаляется. Для затронутого старого использования обеспечьте ошибки компиляции/перепекания/валидации. Следуйте ADR-0002; метка совместимости не отменяет правило.
3. Увеличьте VERSION относительно текущего master. Первое принятие политики заменяет историческую 2022.1.0.wip на 2026.1.1-dev; это не восстановленная история релизов.
4. Добавьте ## 2026.1.21-dev - 2026-10-04 в оба чейнджлога с точным новым идентификатором. Дата заметки master — дата коммита по UTC. Каждая запись содержит непустой раздел ### Migration / ### Миграция; явно пишите, если миграция проекта не нужна, и почему. Unreleased — место для черновика, а не замена датированной записи опубликованного шага. Сохраняйте предыдущие записи, чтобы пропущенные версии мигрировались последовательно.
5. Для каждого удаления/замены заполните исчерпывающую запись миграции ниже и привяжите обязательное решение генерируемого контракта к точным исходному/целевому хешам. Проверяйте семантику даже при пустом статическом diff.
6. В том же изменении обновите ответственные руководства, примеры, оба языка и маршрутизацию AGENTS.md. Через владельцев перегенерируйте затронутые модели/справочники, диаграммы/скриншоты, сниппеты, состояние переводов, сайт/поиск/маршруты, оценку ИИ и данные для ИИ в порядке зависимостей. Полный маршрут задаёт ведение документации.
7. Выполните затронутые проверки native/скриптов/конфигурации/контента/пакетов, отрицательные тесты старого использования и положительные тесты неизменённого/нового использования. Проверьте версии/чейнджлоги и всю необходимую документацию/сайт. Запишите точные результаты, решения по совместимости/ABI/ресурсам и ограничения; номер версии сам по себе не меняет совместимость выполнения.
8. Перед разрешённым коммитом/публикацией выполните валидатор обновления относительно фактической исходной ревизии. CI проверяет каждый входящий шаг master, а не только конечный номер. Публикуйте только по разрешению владельца и сохраняйте опубликованный tip предком.

python BuildTools/docs_engine_version.py --check --branch master --baseline-git-ref HEAD
python BuildTools/tests/test_engine_version.py

Для проверки диапазона уже оформленных коммитов:

python BuildTools/docs_engine_version.py --check --branch master   --baseline-git-ref <previous-master-sha> --target-git-ref <new-master-sha> --history

Проверка исходников --check работает без Git. Для сравнения нужны точные доступные исходная и целевая Git-ревизии. Нельзя обходить отсутствующую исходную ревизию или неполную историю. CI сравнивает итоговый head PR с его целевой базой; push проверяет всю входящую цепочку первого родителя. Старые ревизии до принятия политики требуют обычного аудита всего диапазона исходников.

Исчерпывающая запись миграции

Для каждого удалённого или заменённого контракта пишите отдельную запись со всеми пунктами. Указывайте точные символы, файлы, поиски, порядок, значения и ожидаемые результаты; агент не должен угадывать замену или продуктовую политику.

1. Точная вводящая версия и диапазон старых/новых ревизий; все затронутые бэкенды, роли, платформы, перегрузки, настройки, поля, форматы контента и сохранённые свойства.
2. Старое имя/сигнатура/ключ/значение и первоначальный смысл; новая декларация и смысл; причина удаления. Перечислите сохранённые инварианты: единицы, числовые ID, специальные значения, значения по умолчанию, порядок, владение и побочные эффекты.
3. Команды/шаблоны обнаружения и точная диагностика компилятора/анализатора/пекаря/валидатора, включая динамически объявленные ссылки конфигурации/контента. Укажите способ доказать, что проект не использует затронутую поверхность.
4. Полные примеры до/после и однозначные преобразования: импорты/колбэки, все затронутые скриптовые бэкенды, native-расширения, конфигурация и авторский контент. Явно разрешите перегрузки и крайние случаи; при отсутствии замены укажите судьбу удалённой возможности.
5. Упорядоченные шаги регенерации, конфигурации, компиляции, перепекания, сброса кеша и упаковки для всех сторон/ролей. Ссылайтесь на поддерживаемых исполняемых владельцев, а не инструменты частной игры.
6. Преобразование сохранённых данных, точные операции MigrationRule, где применимо, резервная копия/изолированное восстановление, значения по умолчанию/отсутствующие/старые значения, идемпотентность и граница отката. Явно пишите, если миграция данных не нужна.
7. Последствия для маркера сетевой совместимости, ABI/обновлятора/схем ресурсов, запреты смешанных версий, порядок развёртывания и откат. Явно перечислите неизменяемые идентификаторы.
8. Проверки приёмки: затронутое старое использование завершается ошибкой до игрового процесса, незатронутое сохраняет результаты, мигрированное/новое проходит, необходимые пути сохранения/восстановления/бэкендов выполнены. Запишите точные свидетельства завершения и решения владельца, ещё блокирующие обновление.

Английские и русские инструкции должны совпадать по смыслу. При пропуске нескольких обновлений выполняйте записи от старых к новым с учётом промежуточных границ данных и перепекания. Git diff, ссылка на реестр или «обновите вызовы» не заменяют конкретную инструкцию миграции.

Актуальный API и миграции БД

Engine поддерживает только актуальный API выбранной ревизии. Нет старых алиасов API, разрешающего разбора прежних ключей, запасной семантики и общих режимов старого выполнения. Существующие значения сохраняют первоначальный смысл; удалённый ID перечисления/свойства нельзя переиспользовать для переинтерпретации сохранённых значений. Исправление документированного дефекта восстанавливает смысл и сопровождается проверкой инварианта; намеренная смена допустимого старого случая является заменой.

Существующая обработка MigrationRule — узкое исключение для преобразования сохранённых сущностей/свойств. Она не сохраняет старый API вызовов/конфигурации/контента и не разрешает общую миграцию бизнес-данных БД. Опишите точное старое/новое сохранённое свойство или ссылку и докажите преобразование на изолированных данных; продуктовые бизнес-преобразования остаются у проекта. Центральный маркер MigrationRule Version — отдельный вход хеша совместимости, а не счётчик публичной версии. Необходимые отказы старому бинарнику помечаются существующим маркером временной совместимости; этот маркер не разрешает шим старого API.

Обновление без миграции проекта либо сохраняет все используемые контракты, либо явно завершается ошибкой компиляции/перепекания/валидации затронутого использования. Переинтерпретация смысла при прежней форме, тихое приведение, подстановка значения по умолчанию и ошибка только после начала обычного игрового процесса недопустимы. Если компилятор не различает старое использование, введите отдельный идентификатор/тип/формат и валидатор во владении исходников.

Срез, стабилизация и патчи

1. Владелец выбирает и фиксирует точный проверенный SHA/версию master, матрицу платформ и полномочия стабилизации/патчей. Сделайте срез release/YEAR.MAJOR на этом SHA и задайте YEAR.MAJOR.MINOR.0-rc; запишите фиксированный срез и совокупные миграции на обоих языках. Создание ветки/тега и публикация требуют команды владельца.
2. Независимо начните следующий major master с minor ноль. Исправления релизной ветки сохраняют год/major/minor среза и увеличивают patch один раз на изменение первого родителя, сохраняя -rc при стабилизации. Документируйте и проверяйте каждый патч столь же полно, как изменения master.
3. Выпустите проверенного кандидата снятием -rc, сохранив patch. В этом переходе разрешены только VERSION и документация/данные документации; изменение кода/сборки/тестов требует следующего патча стабилизации и повторной квалификации.
4. Дальнейшие исправления релиза увеличивают patch без суффикса. Переносите только одобренные исправления с тестами, миграциями и документацией фактического поведения ветки; не вливайте целиком поздние добавления API master в фиксированный срез. Если исправлению нужна новая несовместимая семантика, задайте отдельный контракт и явную миграцию вместо смены смысла существующих значений.
5. Выполните docs_engine_version.py --check --branch release/YEAR.MAJOR относительно фактической исходной ревизии и полную матрицу квалификации. Публикуйте неизменяемые теги v<version> и заметки GitHub только после прямого разрешения. Явно ведите происхождение релиза и политику поддержки/переноса патчей; эта будущая процедура не утверждает, что релизные ветки и исторические снимки сайта уже существуют.

Идентификаторы и потребители

BuildTools/engine_version.py используется CMake, native-генератором и документацией. Изменения VERSION и Git-ссылок Engine инвалидируют генерируемые метаданные. Логи запуска выводят идентификатор/ревизию Engine отдельно от игры; вложенный архив не наследует Git-идентификатор родительского проекта. Навигация/маршруты сайта и данные для ИИ используют ту же версию, а ссылка версии открывает чейнджлог выбранного языка. Документация остаётся обновляемым каналом current/master; снимками владеет ADR-0006. Исторические аннотации Since сохраняют первоначальные значения. Брендинг проекта, версии Android/установщиков и хеши пакетов принадлежат проекту.

Владение исходными данными

• VERSION, BuildTools/engine_version.py, BuildTools/docs_engine_version.py, BuildTools/tests/test_engine_version.py
• BuildTools/cmake/helpers/EngineVersion.cmake, BuildTools/cmake/stages/Codegen.cmake, BuildTools/codegen.py, Source/Frontend/ApplicationInit.cpp
• .github/workflows/validate.yml, AGENTS.md, Docs/documentation-manifest.json, BuildTools/docs_site.py, BuildTools/docs_ai_delivery.py