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

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

Навигация, маршруты и данные для ИИ ссылаются на VERSION, не копируя значение. Шаблон Jekyll включает корневой файл напрямую при сборке.

Нотация

Поля 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 получает новый minor и датированные двуязычные заметки: merge, документация, тесты, CI, зависимости и отмены тоже. Перед интеграцией согласуйте исправления рабочей ветки с последним master; прямой push нескольких коммитов должен соблюдать правило на каждом шаге. Незалитые коммиты переносите rebase на полученный tip; merge нужен только для разошедшихся опубликованных историй. Перед публикацией пересчитайте версию и сохраните опубликованные предки.

1. Запишите точные исходную и целевую ревизии, проверьте весь диапазон исходников/тестов/документации и перечислите затронутые поверхности и инварианты смысла существующих значений.
2. Сохраните смысл всех существующих допустимых входов. Добавление/расширение сохраняет старые случаи; замена получает отдельное имя, тип, ключ или явную границу формата, а прежний API удаляется. Для затронутого старого использования обеспечьте ошибки компиляции/перепекания/валидации. Следуйте ADR-0002; метка совместимости не отменяет правило.
3. Увеличьте VERSION относительно текущего master. Первое принятие политики заменяет историческую 2022.1.0.wip на 2026.1.1-dev; это не восстановленная история релизов.
4. Замените заголовок предыдущей записи ## Current - <дата> её прежним идентификатором из VERSION, затем добавьте ## Current - <дата UTC> в оба чейнджлога. Валидатор берёт из VERSION номер только этой новой записи; исторические заголовки сохраняют точные идентификаторы. Дата заметки 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 не нужен. Сравнение требует точных доступных исходной и целевой ревизий; отсутствие или неполную базу обходить нельзя. PR сравнивает итоговый head с базой, 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

CMake использует файловые Git-зависимости; CONFIGURE_DEPENDS обнаруживает packed-to-loose refs, проверенные в test_engine_version.py.