# Выпуск релиза

Как выпускать Russiano2D: что проверить, как собрать, упаковать, подписать

контрольными суммами и опубликовать сразу на **два** хостинга.

Два хоста — две роли:

| Хост | Remote | Доступ | Роль |
|---|---|---|---|

| **hub.mos.ru** | `origin`, первая push-цель | **публичный** | основной: исходники и вся история |
| **gitverse.ru** | `origin`, вторая push-цель, и `gitverse` | публичный | зеркало кода |

* ссылки в README, ссылки в документации и бейджи ведут на hub.mos.ru — он основной;
* **релиз — это `dist/` в репозитории**, он раздаётся оттуда на обоих хостах,
  отдельных «релизов» с выгрузкой нет (раздел 6);
* собирает и публикует локальный `build_and_push.sh`: поднимает версию,
  собирает все платформы, пушит ветку и тег `vX.Y.Z` (раздел 5.6);
* пайплайн на GitVerse написан, но **выключен** (раздел 5.1);
* GitLab-пайплайн на hub.mos.ru убран — раннера там не было (раздел 5.1).

---

## 0. Блокеры публичного релиза

Пока не закрыты эти пункты, публичный релиз выпускать нельзя.

### 0.1. Лицензия выбрана (закрыто)

В корне лежит `LICENSE` — авторская лицензия: движок можно использовать,
менять, распространять и продавать без отчислений; игры, сделанные на нём,

распространяются свободно. В лицензии прямо сказано, что движок русский и
делает его русский автор: если это не нравится — движком не пользуются.
Уведомления зависимостей сохраняются отдельно, в `THIRD_PARTY_NOTICES.md`.

`tools/release.py` в настоящем (не `--dry-run`) режиме требует наличия
`LICENSE` — теперь файл есть, блокер снят. Карта вариантов осталась в
разделе 3 как справка: если владелец решит сменить лицензию на стандартную
(MIT, Apache-2.0 и т. п.), порядок действий там же.

### 0.2. Права на демо-ассеты не подтверждены

`demos/assets/art/**` собраны `tools/make_demo_assets.py` из исходников,
лежащих **вне** репозитория (`R2D_SOURCE_ART`), а происхождение
`assets/audio/**` в репозитории не зафиксировано. До релиза владелец должен
подтвердить права либо исключить эти файлы из поставки. Подробнее —
`THIRD_PARTY_NOTICES.md`, раздел «Ассеты».

### 0.3. Путь до репозитория уточнён (закрыто)

Проект живёт по адресу <https://hub.mos.ru/dem4ev48/russiano2d>, зеркало —
<https://gitverse.ru/Nikide/russiano2d>. Remote'ы настроены так:

```bash
git remote -v

# origin    git@hub.mos.ru:dem4ev48/russiano2d.git  (fetch)
# origin    git@hub.mos.ru:dem4ev48/russiano2d.git  (push)
# origin    git@gitverse.ru:Nikide/russiano2d.git   (push)
# gitverse  git@gitverse.ru:Nikide/russiano2d.git

```

---

## 1. Версия

Версия живёт в одном месте — `project(... VERSION x.y.z ...)` в
`CMakeLists.txt`. Скрипт релиза читает и меняет именно её.

Схема — семантическое версионирование:

| Что изменилось | Какую цифру поднимать |
|---|---|
| ломающее изменение API | `MAJOR` (0.x — пока не обещаем стабильность) |
| новая возможность | `MINOR` |
| исправление | `PATCH` |

Поднять патч-версию на единицу, ничего не собирая:

```bash
python3 tools/release.py --bump          # 0.1.0 → 0.1.1, печатает новую версию
python3 tools/release.py --bump --dry-run  # посмотреть, ничего не меняя
```

В stdout уходит только номер (`0.1.1`) — его удобно подхватывать в скриптах.
Локальный `build_and_push.sh` делает это сам в начале каждого запуска
(`BUMP=0` отключает), причём **до** сборки: иначе пакеты и README в `dist/`
соберутся со старым номером. Сам тег скрипт не ставит — тег запускает релиз
на GitVerse:

```bash
git push origin v0.1.1
```

Одновременно дополнить `CHANGELOG.md`: записи из `[Unreleased]` переезжают в
раздел новой версии с датой.

---

## 2. Сборка и тесты

### 2.1. Debug — для проверок локально

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
```

### 2.2. Release — для поставки

```bash
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release -j
```

Для сборки скриптов внутрь бинарника (байткод QuickJS):

```bash
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release \
      -DR2D_EMBED_SCRIPTS=ON -DR2D_EMBED_DIR=demos
```

Полезные переключатели: `R2D_ENABLE_IMGUI`, `R2D_ENABLE_RMLUI`,
`R2D_ENABLE_AUDIO`, `R2D_ENABLE_HOTRELOAD`, `R2D_SANITIZE`.

### 2.3. Что прогоняется

| Набор | Чем | Нужен GPU |
|---|---|---|
| C-тесты JSON и ChaCha20-Poly1305 | `build/tests/r2d_json_test`, `build/tests/r2d_crypto_test` | нет |
| Юнит-тесты логики `$` | `qjs tests/js/*_test.mjs` (см. `docs/AGENT_API.md`) | нет |

| Публикация релиза из `dist/` | `.gitlab-ci.yml` (hub.mos.ru) и `.gitverse/workflows/publish-dist.yaml` — только выгрузка файлов, без сборки | секрет `RELEASE_API_KEY` нужен только на GitVerse |

| Агентские тесты движка | `python3 tools/run_tests.py` (`--fast` — быстрый набор) | **да** |
| Сборка игры в один файл | `tests/agent/build_test.py` | **да** |

Полный прогон:

```bash
python3 tools/run_tests.py
```

Быстрый (около минуты) и понятный локально:

```bash
python3 tools/run_tests.py --fast
```

Важно: раннер различает `ok`, `fail` и `skip`: пропуск (нет дисплея, нет
ассета) **не считается успехом**. Если релизная проверка дала `skip`, это
надо объяснить, а не «зачесть».

---

## 3. Выбор лицензии (справка)

Лицензия уже выбрана и лежит в `LICENSE` — авторская: движок можно
использовать и продавать без отчислений, игры распространять свободно. Она

не «максимально либеральная»: в ней прямо сказано, что движок русский и делает
его русский автор, и что тем, кому этот факт не нравится, пользоваться им не
стоит. Раздел оставлен на случай, если владелец захочет перейти

на стандартную лицензию. Важное
обстоятельство: движок **статически линкует** MIT/Apache/zlib-зависимости
(см. `THIRD_PARTY_NOTICES.md`), ни одна из них не требует открывать код
проекта.

| Кандидат | Плюсы | Минусы |
|---|---|---|
| **MIT** | максимально коротко и привычно для игровых движков; совместима со всеми зависимостями; легко читается | нет явного патентного гранта; нет условия делиться улучшениями |
| **Apache-2.0** | явный патентный грант и защита от патентных исков; хорошо для корпоративного использования | длиннее и «юридичнее»; требует сохранять NOTICE; несовместима с GPLv2 |
| **BSD-2/3-Clause** | почти как MIT, вариант с запретом использовать имя проекта в рекламе | патентный вопрос тоже не покрыт |
| **zlib** | как у SDL; очень либеральна, коротка | мало кто читает её как «бренд»; патентного гранта нет |
| **MPL-2.0** | файловый копилефт: правки самих файлов открываются, остальное можно закрывать | сложнее для пользователей; не «просто игру возьми» |
| **GPL-2.0/3.0** | гарантирует открытость производных | несовместима с проприетарными играми на движке; закрывает коммерческие форки |
| **Проприетарная / «все права защищены»** | полный контроль | публичный репозиторий становится почти бесполезен для сообщества; часть зависимостей всё равно требует уведомлений |
| **Двойная (например, MIT + коммерческая)** | открытость для сообщества и платный вариант для компаний | нужен CLA и юридическая работа; пугает часть контрибьюторов |

Что учесть при выборе:

* zlib/MIT/Apache-2.0/BSD — «отпускают» код, но требуют сохранить уведомления
  зависимостей (они уже собраны в `THIRD_PARTY_NOTICES.md`).
* Если хочется, чтобы улучшения движка возвращались в общий код — MPL-2.0 или
  GPL, но это ограничит использование в проприетарных играх.
* Шрифты (SIL OFL) и ассеты — отдельные лицензии, лицензия кода их не
  заменяет.

После выбора:

1. положить полный текст в `LICENSE` в корне;
2. добавить строку о лицензии в `README.md` (правит владелец);
3. добавить `LICENSE` в поставку — `tools/release.py` копирует его
   автоматически, если файл есть.

---

## 4. Упаковка

```bash
python3 tools/release.py --dry-run          # план, ничего не меняется
python3 tools/release.py --version 0.2.0    # реальный выпуск
```

Скрипт:

1. поднимает версию в `CMakeLists.txt` (если задан `--version`);
2. собирает Release в `build-release/`;
3. гоняет C-тесты и qjs-тесты;
4. раскладывает `dist/<os>-<arch>/`: бинарник, `assets/`, `game/`,
   `README.md`, `CHANGELOG.md`, `THIRD_PARTY_NOTICES.md`, `LICENSE` (если есть);
5. пишет `SHA256SUMS.txt` внутри пакета и сводный `dist/SHA256SUMS.txt`
   по архивам;
6. делает архивы `.tar.gz` (Linux/macOS) или `.zip` (Windows);
7. ставит аннотированный тег `vX.Y.Z`.

Полезные ключи:

| Ключ | Смысл |
|---|---|
| `--dry-run`, `-n` | печатает план, не пишет и не собирает |
| `--yes` | не спрашивать подтверждение (для скриптов) |
| `--platform linux-x86_64,windows-x86_64` | какие платформы упаковать |
| `--build-dir DIR` | каталог сборки (по умолчанию `build-release`) |
| `--out DIR` | каталог артефактов (по умолчанию `dist`) |
| `--with-demos` | положить в пакет ещё и `demos/` |
| `--force` | пересобрать непустой `dist/<os>-<arch>/` |
| `--skip-build` / `--skip-tests` / `--skip-tag` | осознанно пропустить шаг |

Проверка контрольных сумм перед публикацией:

```bash
cd dist && shasum -a 256 -c SHA256SUMS.txt
```

**Push и теги скрипт не делает.** Их публикует человек (раздел 6) — чтобы
случайный запуск не отправил недоделанный релиз в оба хоста.

---

## 5. CI/CD

> **CI выключен.** Релизы собираются и публикуются локально:
> `build_and_push.sh` поднимает версию, собирает все платформы, коммитит,
> пушит ветку и тег `vX.Y.Z` на оба хостинга. Готовые сборки лежат в `dist/`
> репозитория — отдельной выгрузки релизов нет (раздел 6).

### 5.1. Что где стоит

| | gitverse.ru | hub.mos.ru |

|---|---|---|

| Файл | `.gitverse/workflows/release.yaml` | — |
| Роль | пайплайн написан, но **выключен** | CI нет |
| Когда | только ручной запуск из вкладки CI/CD | — |
| Платформы | Linux x86_64 (нативно) + Windows x86_64 (MinGW) | — |

У пайплайна **нет автоматического триггера** — только `workflow_dispatch`,
чтобы случайный пуш тега ничего не запускал. Как включить обратно, написано
в шапке самого файла: вернуть триггер по тегу и завести секрет
`RELEASE_API_KEY`.

GitLab-пайплайн с hub.mos.ru убран целиком: `.gitlab-ci.yml` и `docs/RUNNER.md`
удалены. Раннера там не было, WAF отдавал `403` на запросы с наших машин —
пайплайн проходил линтер, но не собирал ничего.

**macOS в CI не собирается.** Его собирает локальный `build_and_push.sh` и
кладёт в `dist/` репозитория.

Когда пайплайн включат, он будет работать так: два параллельных job'а сборки и
третий, публикующий релиз.

| Job | Что делает |
|---|---|
| `linux` | apt-зависимости, затем `tools/autobuild.py --no-docker --platforms linux-x86_64` |
| `windows` | mingw-w64 + freetype под MinGW, затем `--platforms windows-x86_64` |
| `release` | `needs: [linux, windows]`: забирает оба архива, считает `SHA256SUMS.txt`, создаёт релиз |

Сборка идёт **без Docker**: облачный раннер GitVerse — это уже изолированный
контейнер, Docker внутри него недоступен. Тот же `tools/autobuild.py`, что и
локально, собирает Linux нативно, а Windows — кросс-компилятором MinGW на этой
же машине.

Артефакты, которые он бы собрал:

| Файл | Размер (ориентир) |
|---|---|
| `russiano2d-linux-x86_64.tar.gz` | ~10 МБ |
| `russiano2d-windows-x86_64.zip` | ~11 МБ |
| `SHA256SUMS.txt` | байты |

### 5.2. Windows: MinGW-кросс-компиляция

Windows собирается **mingw-w64 на Linux-раннере**, а не MSVC. Так же его собирает
локальный `tools/autobuild.py --with-windows`, и именно так собран
`dist/windows-x86_64/russiano2d.exe`, лежащий в репозитории. Один способ сборки
на локальную машину и на CI — значит, одна и та же ловушка не всплывает дважды.

Что нужно, кроме самого `mingw-w64`:

* **freetype под MinGW** — его требует RmlUi, а готового пакета в Ubuntu нет.
  Поэтому freetype собирается из исходников (`--host=x86_64-w64-mingw32`,
  `--without-harfbuzz --without-bzip2 --without-brotli --without-png
  --without-zlib`) и ставится в кросс-корень `/usr/x86_64-w64-mingw32` — ровно
  это делает `tools/docker/Dockerfile.linux-builder` при `WITH_MINGW=1`;
* рантайм MinGW линкуется статически (см. `CMakeLists.txt`), иначе `.exe`
  требовал бы рядом `libstdc++-6.dll` и `libgcc_s_seh-1.dll`.

Кросс-корень переопределяется переменной окружения `R2D_MINGW_ROOT`:
`tools/autobuild.py` подставляет её в `CMAKE_FIND_ROOT_PATH`.

### 5.3. Секрет для публикации релиза

Релиз создаёт действие `actions/create-release@v1`, ему нужен публичный
API-ключ GitVerse:

1. GitVerse → настройки профиля → API-ключи → создать ключ с правом
   **«Репозитории → Запись»**;
2. Настройки репозитория → «Секреты и переменные» → секрет **`RELEASE_API_KEY`**.

> **Имя секрета не должно начинаться с `GITVERSE_`** — платформа запрещает
> такие префиксы. Пример с `secrets.GITVERSE_API_KEY` в документации GitVerse
> неверен: секрет с таким именем создать не даст.

Без секрета сборка пройдёт, а `release`-job упадёт на авторизации.

### 5.4. Лимиты и кэш

Облачные раннеры GitVerse дают **1000 минут** в месяц публичным репозиториям,
но **не больше 30 минут на одну задачу**. Отсюда два решения:

* Linux и Windows — **параллельные** job'ы: у каждого свой бюджет в 30 минут,
  и они не отнимают время друг у друга;
* зависимости кэшируются (`actions/cache`): CMake FetchContent тянет с github.com
  SDL3, SDL3_image, SDL3_mixer, QuickJS-ng, Box2D, RmlUi, Dear ImGui, glslang и
  SPIRV-Cross — это самая долгая часть сборки.

Ключ кэша статический (`r2d-deps-linux-v1`, `r2d-deps-windows-v1`): пины
зависимостей заданы коммитами в `cmake/Dependencies.cmake` и
`cmake/Shaders.cmake`, поэтому ключ не «залипает». Меняете пины — поднимаете
версию в ключе.

Артефакты между job'ами тоже расходуют квоту: **500 МБ на все репозитории**,
срок жизни — 30 дней. Один прогон кладёт ~21 МБ.

### 5.5. Чего в CI не бывает и почему

* **Тесты не запускаются.** Пайплайн только собирает и публикует: прогон
  `tools/run_tests.py` и агентские тесты требуют реального SDL_GPU-устройства
  (Vulkan / Metal / DirectX 12), которого на раннере нет. Это локальный шаг.
  Отдельно отметим: старый GitLab-пайплайн тесты декларировал, но ни разу не
  выполнялся, так что регрессии ловил не он, а локальный прогон.

* **Агентские тесты** (`tests/agent/*_test.py`) не запускаются нигде в CI.
  Они поднимают движок с `--headless`, но движок всё равно создаёт
  SDL_GPU-устройство (Vulkan / Metal / DirectX 12). На раннере GPU-драйвера
  нет — прогон либо падает, либо уходит в `skip`. Это локальный шаг:
  `python3 tools/run_tests.py`.
* **Сборка игры в один файл** (`./russiano2d build ...`) не проверяется в CI:
  она шифрует груз и на macOS переподписывает бинарник (`codesign`).
  Локально: `tests/agent/build_test.py`.
* **GPU-скриншоты и рендер-проверки** — та же причина. Проверяются глазами
  и локальными агентскими тестами.

* **macOS не собирается** — его собирает локальный `build_and_push.sh`.

Честная формулировка для релизных заметок: CI подтверждает, что движок

**собирается** под Linux и Windows; всё, что касается тестов, GPU и окна,
проверено локально на машине разработчика.

### 5.6. Как выпускается релиз сейчас

CI выключен, поэтому весь выпуск делает локальный `build_and_push.sh`:

1. поднимает патч-версию в `CMakeLists.txt` (`0.1.0 → 0.1.1`);
2. собирает macOS, Linux и Windows в `dist/`;
3. пересобирает `README.md`/`AGENTS.md` в пакетах из `docs/`;
4. коммитит (`git add -A` + `git add -f dist`) и пушит ветку на оба хостинга;
5. ставит аннотированный тег `vX.Y.Z` и пушит его туда же.

Если сборка упала, версия откатывается, а коммит и пуш не делаются
(`ALLOW_PARTIAL=0` по умолчанию).

Релиз — это и есть содержимое `dist/` в коммите, на который указывает тег.
Ссылки для скачивания — в разделе 6.

Раздел 5.1–5.5 описывает пайплайн на GitVerse: он написан и лежит в
репозитории, но выключен — пригодится, если локальная сборка надоест.

---

## 6. Публикация

**Релиз — это `dist/` в репозитории.** Отдельной выгрузки релизов ни на одном
хостинге нет: архивы, распакованные каталоги и `SHA256SUMS.txt` лежат прямо в
`dist/` и раздаются оттуда.

* <https://hub.mos.ru/dem4ev48/russiano2d/-/tree/main/dist>
* <https://gitverse.ru/Nikide/russiano2d/content/main/dist>

Тег `vX.Y.Z` — метка релиза: он указывает, какому коммиту соответствует
содержимое `dist/`. Ставит и пушит его `build_and_push.sh` (шаг 5).

Мульти-пуш: у `origin` две push-цели — hub.mos.ru (первая) и gitverse.ru
(вторая), поэтому один `git push` уходит сразу на оба хостинга.

```bash
git remote -v

# origin    git@hub.mos.ru:dem4ev48/russiano2d.git  (fetch)
# origin    git@hub.mos.ru:dem4ev48/russiano2d.git  (push)
# origin    git@gitverse.ru:Nikide/russiano2d.git   (push)
# gitverse  git@gitverse.ru:Nikide/russiano2d.git

```

Отправка ветки и тега:

```bash

git push origin main          # основная ветка — сразу на оба хоста

git push origin --all         # все ветки
git push origin --tags        # теги
git push origin v0.2.0        # конкретный тег

git push gitverse main        # только на GitVerse
```

Проверить, что доехало до каждого хоста:

```bash
git ls-remote origin main        # hub.mos.ru (ls-remote берёт fetch-адрес)
git ls-remote gitverse main      # GitVerse
git ls-remote origin v0.2.0      # тег
```

Обе команды должны показать один и тот же SHA — тот, что у вас в
`git rev-parse main`.

**Порядок целей важен.** `git` идёт по push-адресам по очереди, и что станет
с остальными — зависит от типа ошибки:

| Что случилось с хостом | Что делает git | Код возврата |
|---|---|---|
| отклонил ссылку (`non-fast-forward`) | идёт к следующему адресу | `1` |
| недоступен (нет репозитория, нет сети, отказ в доступе) | **прекращает обход**, остальные адреса push не получат | `128` |

hub.mos.ru стоит первым специально: если GitVerse отклонит пуш или оборвёт
соединение, пуш в Москву уже состоялся. Обратная сторона — при недоступном
hub.mos.ru зеркало тоже не обновится; тогда досылайте отдельно:
`git push gitverse main`.

В обоих случаях код возврата ненулевой, даже если часть хостов коммит уже
получила, — поэтому `build_and_push.sh` после пуша отдельно проверяет каждый
адрес и печатает, кто отстал.

Если GitVerse отверг пуш (например, разошлась история — см. раздел 7), а в
Москву всё уехало, повторяйте только проблемный хост:

```bash
git push gitverse main

```

`--mirror` для публикации не используйте: он удаляет на сервере всё, чего нет

локально. Локальный `git clone --mirror` в отдельный каталог остаётся
дополнительным бэкапом.

---

## 7. Расхождение историй

Симптом: `git push origin main` отклонён (`non-fast-forward`), потому что на
зеркале есть коммиты, которых нет локально (например, при инициализации
репозитория через веб-интерфейс GitLab).

Что делать — по порядку:

1. Посмотреть, что именно разошлось:

   ```bash

   git fetch gitverse
   git log --oneline --left-right --graph main...gitverse/main

   ```

2. Если на зеркале осмысленная история (README, `.gitignore`) — слить, не
   перезаписывая:

   ```bash

   git merge --allow-unrelated-histories gitverse/main

   # разрулить конфликты, закоммитить
   git push origin main
   ```

3. Если история на зеркале — мусор от неудачной инициализации и владелец
   согласен её заменить:

   ```bash
   git push --force-with-lease origin main
   ```

   `--force-with-lease` безопаснее `--force`: push пройдёт, только если
   зеркало не изменилось с последнего `fetch`.

4. Никогда не делать `git push --force` «на всякий случай» в `origin`:
   перезапись публичной истории ломает форки и PR. Принудительный push —
   только после явного решения владельца.

Тег, указывающий на уже удалённый коммит, после перезаписи истории лучше
пересоздать осознанно:

```bash

git push --delete gitverse v0.2.0   # если тег успел уехать

git tag -d v0.2.0
python3 tools/release.py --version 0.2.0 --skip-build --skip-tests
```

---

## 8. Чек-лист релиза

- [x] Лицензия выбрана, `LICENSE` лежит в корне, упомянута в `README.md`
- [ ] Права на демо-арт и звук подтверждены (или файлы исключены)
- [x] Путь до репозитория уточнён: <https://hub.mos.ru/dem4ev48/russiano2d>

      (зеркало — <https://gitverse.ru/Nikide/russiano2d>)

- [ ] `CHANGELOG.md` обновлён, `[Unreleased]` разобран
- [ ] Локально: `python3 tools/run_tests.py` — без `fail`; `skip` объяснены
- [ ] Локально: собраны Release-бинарники (при необходимости — игры в один файл)

- [ ] `./build_and_push.sh` — поднял версию, собрал `dist/`, запушил ветку и тег
      (или вручную: `python3 tools/release.py --version x.y.z`, затем раздел 6)

- [ ] `dist/*/SHA256SUMS.txt` проверен (`shasum -a 256 -c`)
- [ ] `THIRD_PARTY_NOTICES.md` актуален; тексты лицензий в поставке

- [ ] Ветка и тег `vX.Y.Z` доехали до обоих хостов (скрипт печатает сверку;
      вручную — `git ls-remote origin main` и `git ls-remote origin vX.Y.Z`)
- [ ] `dist/` в коммите тега открывается по ссылке и архивы скачиваются:
      <https://hub.mos.ru/dem4ev48/russiano2d/-/tree/main/dist> и
      <https://gitverse.ru/Nikide/russiano2d/content/main/dist>

- [ ] Локальный mirror-бэкап обновлён (`git clone --mirror` или бэкап инстанса)