# XC_VM Контрольный список для подготовки релиза

Пошаговое руководство по подготовке и публикации пресс-релиза XC_VM.

---

## 1. Журнал изменений

**Reset the build output, then generate the commit log (work commits only):**

```bash
make new                 # wipe + recreate dist/ ONCE, at the very start
PREV_TAG=$(git describe --tags --abbrev=0)
git log --pretty=format:"- %s (%h)" "$PREV_TAG"..main > dist/changes.md
```

> ➡️ Запустите `make new` здесь, в самом начале выпуска — он сотрет **и** и воссоздаст `dist/`. Все, что указано ниже, записывается в `dist/` (начиная с `changes.md`), поэтому `make new` должен выполнить **до** это и **никогда больше** перед сборкой — более поздний `make new` удалит `dist/changes.md`.

**Обновить `changelog.json`** в корневом каталоге репозитория — этот файл содержит только изменения для предстоящего выпуска:

```json
{
    "version": "X.Y.Z",
    "changes": [
        "Description of change 1",
        "Description of change 2"
    ]
}
```

Панель автоматически извлекает этот файл из тега release через `GitHubReleases::getChangelog()`.

> 💬 Делайте описания краткими — сосредоточьтесь на улучшениях и исправлениях, с которыми сталкиваются пользователи.

---

## 2. Предварительная проверка

Перед публикацией проверьте, работает ли сборка:

**Проверка качества** (CI использует тот же набор параметров для тега — убедитесь, что он зеленый):

```bash
make dev-tools && make phpstan && make cs && make gates
php tests/phpunit.phar -c tests/phpunit.xml.dist
make dev-clean   # remove the dev tools afterwards, restoring the prod-only vendor/
```

> ➡ ️ Тестовая установка Docker перенесена на шаг 6 — для этого требуется встроенный `dist/XC_VM.zip`.

**Проверка безопасности:** запускается автоматически при нажатии/ PR через `.github/workflows/security-scan.yml` (Semgrep) — никаких действий вручную.

### Восстановление переведенной документации

Документация написана в виде **Только на английском языке** (`docs/en`). Русское дерево
(`docs/ru`) - это артефакт **сгенерированный, зафиксированный**, обновляемый локально перед каждым
release — перевод намеренно **нет** выполняется в CI (он медленный); только CI
создает зафиксированное дерево. Если `docs/en` изменено с момента последнего выпуска:

```bash
make docs-translate      # regenerate docs/ru from docs/en (free, no API key)
make docs-build          # strict build — fails on any broken link/anchor
```

- `make docs-translate` повторно переводятся только те файлы на английском языке, содержимое которых
изменен (для каждого файла в кэше), так что при постепенном выпуске это происходит быстрее.
- **Review and commit the regenerated `docs/ru`** — он включен в единый
отпустите фиксацию (шаг 5). Никогда не редактируйте вручную `docs/ru`.
- Documentation is published **per release, not per push**: `pages.yml` runs when
будет запущена версия **метка** (шаг 7), и документы этого выпуска будут опубликованы в виде
версионный снимок (`X.Y.Z` + псевдоним `latest`) в ветвь `gh-pages` через
`mike`. Правки, объединенные в `main` между выпусками, будут опубликованы на следующем помеченном
освобождение (которое также происходит при повторном создании `docs/ru`). Заголовок материала
селектор версий позволяет читателям переключаться между выпущенными версиями.

---

## 3. Подготовить базовый уровень выпуска

Сначала завершите всю работу с функциями / исправлениями / документами и убедитесь, что она уже включена в `main`.

Установите переменную version один раз и повторно используйте ее во всех приведенных ниже командах:

```bash
VERSION="X.Y.Z"
```

**Выбор `X.Y.Z`:** `MAJOR.MINOR.PATCH` — добавить **заплатка** исправления/небольшие изменения (например,
`2.4.0 → 2.4.1`), **незначительный** для функций обратной совместимости (`2.4.x → 2.5.0`), **главный** для
основные изменения. Исправления - это дополнение к текущей версии. `XC_VM_VERSION`
(заданный на шаге 5) должен соответствовать тегу, который вы публикуете на шаге 7.

> ❗️ Не создавайте отдельную версию-измените фиксацию/push на этом шаге.
> В противном случае `dist/changes.md` будет включать дополнительные фиксации релиза и потребует внесения дополнительных правок.

---

## 4. Удаленные файлы

Перед сборкой сгенерируйте список файлов для удаления при обновлении:

```bash
make generate_deleted_files
```

Это запускает `git diff` между `LAST_TAG` и `HEAD`, извлекает удаленные файлы из `src/`, удаляет префикс `src/` и записывает результат в `src/migrations/deleted_files.txt`.

Если `LAST_TAG` не может быть определено автоматически (нет сети / нет выпусков), передайте его явно:

```bash
make generate_deleted_files LAST_TAG=1.2.16
```

**Просмотрите созданный файл** — убедитесь, что по ошибке в списке нет важных файлов:

```bash
cat src/migrations/deleted_files.txt
```

После проверки `make lb` загружает файл в LB-архив через целевой объект `lb_delete_files_list`; в MAIN файл просто перемещается в полноразмерной копии (отдельного целевого объекта `delete_files_list` нет).

Во время `php console.php update post-update` `MigrationRunner::runFileCleanup()` считывает его и автоматически удаляет перечисленные файлы.

> ❗️ Строки, начинающиеся с `#`, являются комментариями и будут проигнорированы. Вы можете закомментировать файлы, которые хотите сохранить.

---

## 5. Обновите версию и создайте единую фиксацию выпуска

Измените значение постоянной версии, отключите флажок доступа к phpMiniAdmin и снимите пароль в:

> **Зачем отключать `DB_ACCESS_ENABLED` / очищать `DB_ACCESS_PWD`?** phpMiniAdmin - это необработанный
> консоль базы данных удобна при разработке, но ее отправка **включен** приведет к тому, что база данных будет подвержена
> любой, кто доберется до панели. Этот шаг является мерой усиления безопасности — разблокировка никогда не должна
> выходи на улицу в нем.


```text
src/Core/Config/ConstantsInitializer.php
```

Эти часто редактируемые константы равны `define()`s в **верхняя часть файла** (над
class); `appConfig()` считывает их обратно, а `init()` пропускает уже определенные.

**Quick commands:**

```bash
sed -i "s/define('DB_ACCESS_ENABLED', true);/define('DB_ACCESS_ENABLED', false);/" src/Core/Config/ConstantsInitializer.php
sed -i "s/define('DB_ACCESS_PWD', '[^']*');/define('DB_ACCESS_PWD', '');/" src/Core/Config/ConstantsInitializer.php
sed -i "s/define('XC_VM_VERSION', '[0-9]\+\.[0-9]\+\.[0-9]\+');/define('XC_VM_VERSION', '${VERSION}');/" src/Core/Config/ConstantsInitializer.php
```

**Create one final release commit/push:**

```bash
git add src/Core/Config/ConstantsInitializer.php changelog.json src/migrations/deleted_files.txt
git add docs/en docs/ru   # include any doc edits + the regenerated ru (step 2)
git commit -m "Prepare release ${VERSION}"
git push
```

> ❗️ Это устраняет необходимость в многократных фиксациях релиза.

---

## 6. Создавать архивы

> 🤖 **Производственные сборки** обрабатываются действиями GitHub (`.github/workflows/build-release.yml`) при публикации релиза. Ресурсы добавляются автоматически.

**For local builds:**

```bash
make lb
make main
```

> ➡️ Выполните **нет** запуск `make new` здесь — `dist/` уже был сброшен на шаге 1, и повторный запуск приведет к удалению `dist/changes.md`. Цели сборки записываются в существующий `dist/`.

После построения `dist/` должно содержать:

|Файл|Описание|
| --- | --- |
| `XC_VM.zip` |ОСНОВНОЙ установщик (установить скрипт + xc_vm.tar.gz)|
| `xc_vm.tar.gz` |ОСНОВНОЙ архив (установка и обновление)|
| `loadbalancer.tar.gz` |Архив LB (установка и обновление)|
| `hashes.md5` |Контрольные суммы MD5|

> Один и тот же архив используется как для чистой установки, так и для обновлений.
> Скрипт обновления (`src/update`) отфильтровывает двоичные/конфигурационные каталоги во время выполнения, используя жестко заданный список `UPDATE_EXCLUDE_DIRS` внутри самого скрипта Python.

**Verify integrity:**

```bash
cd dist && md5sum -c hashes.md5
```

**Тестовая установка Docker** (см. `tools/test-install/`) — только после сборки, поскольку для этого требуется `dist/XC_VM.zip`:

```bash
bash tools/test-install/test_release.sh
```

При этом создается образ, контейнер запускается с systemd и программа установки запускается автоматически.
`dist/XC_VM.zip` монтируется в контейнер как том, доступный только для чтения.

> ✅ Убедитесь, что панель загружается со значением `http://localhost:8880` и логин администратора работает.

---

## 7. Релиз на GitHub

1. Перейти к [Релизам на GitHub](https://github.com/Vateron-Media/XC_VM/releases)
2. Создайте новый релиз с тегом, указанным на первом шаге
3. Вставьте список изменений в качестве описания выпуска
4. Опубликовать **без прикрепления файлов** — Действия GitHub создадут и прикрепят их

После публикации рабочий процесс будет автоматически запущен:

- Собрать все архивы + контрольные суммы
- Прикрепите их к фиксатору
- Отправьте уведомление в Telegram через `release-notifier.yml`
- Опубликуйте документацию по этой версии на страницах GitHub через `pages.yml` (mike):
моментальный снимок `X.Y.Z` плюс псевдоним `latest`, который можно выбрать из заголовка документа

> ✅ Дождитесь завершения рабочего процесса действий, затем убедитесь, что все файлы доступны для загрузки.

---

## 8. После выпуска

> **ГЛАВНЫЙ перед LB.** Сначала обновите узел **главный**. Его `post-update` узел передает `update`
> подавайте сигнал на каждый LB, когда включено `auto_update_lbs`, чтобы LBS следовали автоматически; сохраняйте основные и LB
> в **та же версия** — LBs считывается база данных MAIN, и может возникнуть перекос в схеме/поведении
> потоковый. Не оставляйте LBs без внимания.


- [ ] Убедитесь, что все 4 ресурса присоединены к релизу
- [ ] Выполнить `md5sum -c hashes.md5` для загруженных файлов
- [ ] Проверьте, отправлено ли уведомление Telegram
- [ ] Тесно связанные с GitHub проблемы / вехи

---

## Если что-то пойдет не так

- **После публикации не удалось выполнить построение действий** — в релизе отсутствуют (или частично) ресурсы. Повторно запустите
сбой рабочего процесса на вкладке Действия; если сам тег неверен, удалите выпуск **и**, который
пометьте (`git push --delete origin vX.Y.Z`), исправьте и пометьте повторно. Не оставляйте опубликованный релиз с
отсутствующие ресурсы — панели извлекают из него `hashes.md5` / архивы.
- **Выпущенный актив поврежден** — опубликовать выпуск исправления **заплатка** (новый тег) вместо редактирования
опубликованный файл; клиенты прикрепляют его к тегу.
- **Плохой релиз уже достиг серверов** — операторы могут понизить рейтинг каждого сервера с помощью панели управления
(**Серверы → Откат версии**, см. [Механизм обновления → Откат](../administration/update-system.md#rollback-downgrade)); на ГЛАВНОЙ сначала автоматически создается резервная копия базы данных. Миграции - это
доступна только переадресация, поэтому, если исправление небольшое, предпочитайте исправление с переадресацией.

---

## Ссылка на команду

Все целевые объекты `make`, использованные во время подготовки релиза, в одном месте.

**Проверка качества** — сначала запустите `make dev-tools`, затем `make dev-clean`, когда закончите:

|Команда|Цель|
| --- | --- |
| `make dev-tools` |Установите инструменты разработки (PHPStan, phpcs) через `composer install`|
| `make phpstan` |Статический анализ (также выявляет синтаксические ошибки)|
| `make phpstan-baseline` |Восстановите базовую линию PHPStan|
| `make cs` |Проверка стиля кода - импорт/гигиена пространства имен (phpcs + Slevomat)|
| `make cs-fix` |Примените исправления в стиле кода на месте|
| `make gates` |PSR-4 регрессионные параметры (для использования в процедурных целях, LB-архив, только для продукта поставщика)|
| `make dev-clean` |Снова удалите инструменты разработки, восстановив только производственную версию `vendor/`.|
| `php tests/phpunit.phar -c tests/phpunit.xml.dist` |Модульные тесты|

**Release prep & build:**

|Команда|Цель|
| --- | --- |
| `make generate_deleted_files` |Регенерировать `src/migrations/deleted_files.txt`|
| `make new` |Wipe + recreate `dist/` — запускается ОДИН раз в начале (шаг 1), перед записью `dist/changes.md`; никогда больше перед созданием|
| `make lb` |Создайте архив LoadBalancer в виде `dist/`|
| `make main` |Соберите ОСНОВНОЙ архив в `dist/`|
| `bash tools/test-install/test_release.sh` |Установочный тест Docker для встроенного выпуска|

**Документация** (английский источник в `docs/en`; `docs/ru` сгенерирован + зафиксирован):

|Команда|Цель|
| --- | --- |
| `make docs-venv` |Одноразовый: локальный venv (сборка + переводы)|
| `make docs-translate` |Восстановить `docs/ru` из `docs/en` (перед выпуском)|
| `make docs-build` |Строгая сборка MkDocs в `./build/site` (что запускает CI)|
| `make docs-serve` |Предварительный просмотр документов в режиме реального времени по адресу `http://127.0.0.1:8000`|