XC_VM/docs/ru/builds/updates_checklist.md

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

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

---

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

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

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

VERSION="X.Y.Z"

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

---

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

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

make generate_deleted_files

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

Если LAST_TAG не определяется автоматически (нет сети / нет релизов), передайте явно:

make generate_deleted_files LAST_TAG=1.2.16

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

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 прогоняет тот же набор на теге — убедитесь, что зелёный):

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

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

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 в корне репозитория — этот файл содержит только изменения для предстоящего релиза:

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

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

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

---

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

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

src/Core/Config/AppConfig.php

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

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 для релиза:

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) при публикации релиза. Файлы прикрепляются автоматически.

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

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-скрипта.

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

cd dist && md5sum -c hashes.md5

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

bash tools/test-install/test_release.sh

Скрипт собирает образ, запускает контейнер с systemd и автоматически выполняет установку. dist/XC_VM.zip монтируется в контейнер как read-only volume.

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

---

7. GitHub релиз

1. Перейти на GitHub 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-тест установки собранного релиза