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

Контрольный список подготовки к выпуску 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 --no-merges --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 запускает один и тот же набор при каждом нажатии на main и при запросах на извлечение, но не для тегов — подтвердите, что он зеленый при фиксации выпуска, как только шаг 5 будет выполнен):

make dev-tools
make phpstan
make cs
make gates
make test-db     # only without a local MariaDB: the unit tests run on MariaDB
php tests/phpunit.phar -c tests/phpunit.xml.dist
make dev-clean   # remove the dev tools afterwards, restoring the prod-only vendor/

Каждая новая миграция может быть отменена. При откате версии (Серверы → Откат версии) изменения, отсутствующие в более старой версии, отменяются вместе с их файлами down/ и пропускаются те, в которых их нет, оставляя изменения схемы без изменений. Перечислите изменения, добавленные с момента последней версии, в которых не было обновленного файла.:

PREV_TAG=$(git describe --tags --abbrev=0)
for f in $(git diff --name-only --diff-filter=A "$PREV_TAG" -- src/migrations/database/up); do
  [ -f "src/migrations/database/down/$(basename "$f")" ] || grep -q '^-- No down file' "$f" || echo "no down file: $f"
done

Напишите недостающие (src/migrations/database/down/<same name>.sql) перед выпуском; миграция, которую действительно невозможно отменить, объясняет причину в комментарии вверху своего файла up, начиная с -- No down file, и приведенный выше цикл прекращает ее перечислять.

➡ ️ Тестовая установка 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.
  • Documentation is published per release, not per push: pages.yml runs when будет запущена версия метка (шаг 7), и документы этого выпуска будут опубликованы в виде версионный снимок (X.Y.Z + псевдоним latest) в ветвь gh-pages через mike. Правки, объединенные в main между выпусками, будут опубликованы на следующем помеченном высвобождение (которое также происходит при регенерации docs/ru). Заголовок материала селектор версий позволяет читателям переключаться между выпущенными версиями.

Языковые файлы панели синхронизации

Новые строки пользовательского интерфейса добавляются только в src/Core/Localization/lang/en.ini. Перед освободите, приведите в соответствие с ним все остальные языковые файлы:

make lang-translate      # translate keys missing vs en.ini, drop keys en.ini no longer has
  • Существующие переводы сохраняются; отсутствующие ключи и значения по-прежнему идентичны текст на английском языке переведен машинным способом; ключи, удаленные из en.ini, являются удалены из всех языков (при запуске они перечислены — проверьте, что ничего ожидаемого нет в этом списке).
  • Переводы кэшируются (build/docs-cache/ini-<lang>.json), поэтому только ключи добавлено с момента появления в сети последнего релиза.
  • Просмотрите разницу между src/Core/Localization/lang/*.ini и зафиксируйте ее с выпуск (шаг 5). Заполнители, такие как {bin} и HTML-теги, должны быть без изменений; см. раздел Добавление пользовательского языка.

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/ConstantsInitializer.php

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

Quick commands:

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:

git add src/Core/Config/ConstantsInitializer.php changelog.json src/migrations/deleted_files.txt
git add src/Core/Localization/lang/   # the synced language files (step 2)
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. Создайте новый выпуск, ориентированный на main, с тегом ${VERSION} из шага 3: обычный X.Y.Z, без префикса v (существующие теги 2.6.0, 2.5.3, ...), равны XC_VM_VERSION
  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 без внимания.

Сначала отмените блокировку кластера, когда это потребуется для обновления. Один раз cluster:db-allowlist apply если MariaDB и Redis MAIN закрыты для флота, узел больше не сможет к ним подключиться. Если это для пути обновления версии требуется узел to — узел, обновленный с помощью устаревшего сигнала update, узел снова перешел в режим 2 для обновления — запустите console.php cluster:db-allowlist undo на ЗАПУСТИТЕ до обновление и снова cluster:db-allowlist apply, как только каждый узел вернется в исходное состояние. режим 2. Смотрите Cluster API.

Никогда не понижайте MAIN ниже уровня, необходимого для его узлов mode-2. Пока любой узел находится в режиме 2 (режим Mode столбец Серверы → Узлы кластера), MAIN должен оставаться в релизе, который обслуживает каждую операцию и раздел реплики, который используют эти узлы — они больше не читают базу данных MAIN, так что больше ничего переносит их. Не следует откатывать MAIN назад после того, как узел был переведен в режим 2, пока он все еще существует: сначала переместите каждый такой узел в режим 1 (mode_down) и только затем выполняйте откат как только в режиме 2 ничего не останется.

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

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

  • После публикации не удалось выполнить построение действий — в релизе нет ресурсов (или они частично доступны). Повторно запустите сбой рабочего процесса на вкладке Действия; если сам тег неверен, удалите выпуск и, который пометьте (git push --delete <remote> X.Y.Z, удаленный сервер так, как его называет git remote), исправьте и повторно пометьте. Не оставляйте опубликованный релиз с отсутствующие ресурсы — панели извлекают из него hashes.md5 / архивы.
  • Выпущенный актив поврежден — опубликовать выпуск исправления заплатка (новый тег) вместо редактирования опубликованный файл; клиенты прикрепляют его к тегу.
  • Плохой релиз уже достиг серверов — операторы могут понизить рейтинг каждого сервера с помощью панели управления (Серверы → Откат версии, см. Механизм обновления → Откат); в MAIN сначала автоматически создается резервная копия базы данных. Миграции выполняются доступно только в прямом эфире, поэтому, если исправление небольшое, предпочитайте использовать исправление с откатом вперед. При использовании cluster API применяются два правила кластера после выпуска и к откату тоже: никогда не опускайтесь ниже уровня, необходимого узлу режима 2, и сначала отмените блокировку, когда для отката нужны узлы, чтобы добраться до базы данных 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 Регрессионные элементы: процедурное использование, LB-архив, только для продуктов поставщика, ключи настроек LB, ссылки на ядро→кластер
make dev-clean Снова удалите инструменты разработки, восстановив только производственную версию vendor/.
make test-db Одноразовый MariaDB в Docker для модульных тестов (без локального сервера)
php tests/phpunit.phar -c tests/phpunit.xml.dist Модульные тесты в MariaDB

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 lang-translate Синхронизировать lang/*.ini с en.ini (перед выпуском)
make docs-build Строгая сборка MkDocs в ./build/site (что запускает CI)
make docs-serve Предварительный просмотр документов в режиме реального времени на http://127.0.0.1:8000