Перейти к содержанию

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

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

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

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

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

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

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

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

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

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

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

make dev-tools && make phpstan && make cs && make gates
php tools/.bin/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 изменено с момента последнего выпуска:

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.
  • Нажатие кнопки изменения документов запускает pages.yml, которая создает и публикует переходите с сайта на страницы GitHub.

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

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

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

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. Удаленные файлы

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

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 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 - это необработанный консоль базы данных удобна при разработке, но ее отправка включен приведет к тому, что база данных будет подвержена любой, кто доберется до панели. Этот шаг является мерой усиления безопасности — разблокировка никогда не должна выходи на улицу в нем.

src/Core/Config/AppConfig.php

Quick commands:

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

Create one final release commit/push:

git add src/Core/Config/AppConfig.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:

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:

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 монтируется в контейнер как том, доступный только для чтения.

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

7. Релиз на GitHub

  1. Перейти к Релизам на GitHub
  2. Создайте новый релиз с тегом, указанным на первом шаге
  3. Вставьте список изменений в качестве описания выпуска
  4. Опубликовать без прикрепления файлов — Действия на GitHub создадут и прикрепят их

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

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

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

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 / архивы.
  • Выпущенный актив поврежден — опубликовать выпуск исправления заплатка (новый тег) вместо редактирования опубликованный файл; клиенты прикрепляют его к тегу.
  • Плохой релиз уже достиг серверов — операторы могут понизить рейтинг каждого сервера с помощью панели управления (Серверы → Откат версии, см. Механизм обновления → Откат); в MAIN сначала автоматически создается резервная копия базы данных. Миграции выполняются доступна только переадресация, поэтому, если исправление небольшое, предпочитайте исправление с переадресацией.

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

Все целевые объекты 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 tools/.bin/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