# Чеклист подготовки релиза XC_VM

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

---

## 1. Подготовить базу для релиза

Сначала завершите все рабочие изменения (feature/fix/docs) и убедитесь, что они уже в `main`.

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

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

> ⚠️ Не делайте отдельный commit/push с bump версии на этом шаге.
> Иначе `dist/changes.md` будет включать лишние релизные коммиты, и вам придётся делать дополнительные правки.

---

## 2. Удалённые файлы

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

```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 main` / `make lb` упакуют файл в архив через `delete_files_list` / `lb_delete_files_list`.

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

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

---

## 3. Предрелизная проверка

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

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

```bash
make dev-tools && make phpstan && make cs && make gates
php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist
make dev-clean   # после проверок убрать dev-инструменты, вернув прод-only vendor/
```

> ℹ️ Тестовая установка в Docker вынесена в шаг 6 — она требует собранного `dist/XC_VM.zip`.

**Security-сканирование:** запускается автоматически при push/PR через `.github/workflows/security-scan.yml` (Semgrep) — вручную ничего делать не нужно.

---

## 4. Changelog

**Сгенерировать лог коммитов (только рабочие изменения):**

```bash
PREV_TAG=$(git describe --tags --abbrev=0)
mkdir -p dist
git log --pretty=format:"- %s (%h)" "$PREV_TAG"..main > dist/changes.md
```

> ⚠️ `mkdir -p dist` обязателен: каталога `dist/` нет на свежем клоне, а `make new` его очищает — без него редирект упадёт с «No such file or directory».

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

```json
{
    "version": "X.Y.Z",
    "changes": [
        "Описание изменения 1",
        "Описание изменения 2"
    ]
}
```

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

> 💬 Описания должны быть краткими — фокус на пользовательских улучшениях и исправлениях.

---

## 5. Обновить версию и сделать единый release commit

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

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

**Быстрые команды:**

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

**Сделать один финальный commit/push для релиза:**

```bash
git add src/Core/Config/AppConfig.php changelog.json src/migrations/deleted_files.txt
git commit -m "Prepare release ${VERSION}"
git push
```

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

---

## 6. Сборка архивов

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

**Для локальной сборки:**

```bash
make new
make lb
make main
```

После сборки в `dist/` должны быть:

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

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

**Проверка целостности:**

```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` монтируется в контейнер как read-only volume.

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

---

## 7. GitHub релиз

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

После публикации workflow автоматически:

- Соберёт все архивы + контрольные суммы
- Прикрепит их к релизу
- Отправит Telegram-уведомление через `release-notifier.yml`

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

---

## 8. После релиза

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

---

## Справочник команд

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

**Проверки качества** — сначала `make dev-tools`, в конце `make dev-clean`:

| Команда | Назначение |
| --- | --- |
| `make dev-tools` | Установить dev-инструменты (PHPStan, PHP-CS-Fixer) через `composer install` |
| `make phpstan` | Статический анализ (ловит и синтаксические ошибки) |
| `make phpstan-baseline` | Перегенерировать baseline PHPStan |
| `make cs` | Проверка стиля — гигиена импортов/namespace (PHP-CS-Fixer, dry-run) |
| `make cs-fix` | Применить исправления стиля |
| `make gates` | Регресс-гейты PSR-4 (procedural-use, LB-archive, vendor-prod-only) |
| `make dev-clean` | Убрать dev-инструменты, вернув production-only `vendor/` |
| `php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist` | Юнит-тесты |

**Подготовка и сборка релиза:**

| Команда | Назначение |
| --- | --- |
| `make generate_deleted_files` | Перегенерировать `src/migrations/deleted_files.txt` |
| `make new` | Очистить выходной каталог `dist/` (перед сборкой) |
| `make lb` | Собрать LoadBalancer-архив в `dist/` |
| `make main` | Собрать MAIN-архив в `dist/` |
| `bash tools/test-install/test_release.sh` | Docker-тест установки собранного релиза |
