- This document describes the process of creating an XC_VM release — a step-by-step guide for developers on updating the version, building archives, and publishing on GitHub. + Step-by-step guide for preparing and publishing an XC_VM release.
--- @@ -9,69 +9,90 @@ ## 📚 Navigation * [🔢 1. Update Version](#1-update-version) -* [🧹 2. Deleted Files](#2-deleted-files) -* [⚙️ 3. Build Archives](#3-build-archives) -* [📝 4. Changelog](#4-changelog) -* [🚀 5. GitHub Release](#5-github-release) +* [🧹 2. Deleted Files (Automated)](#2-deleted-files-automated) +* [🧪 3. Pre-Release Validation](#3-pre-release-validation) +* [⚙️ 4. Build Archives](#4-build-archives) +* [📝 5. Changelog](#5-changelog) +* [🚀 6. GitHub Release](#6-github-release) +* [📢 7. Post-Release](#7-post-release) --- ## 🔢 1. Update Version -* Set the **new `XC_VM_VERSION` value** in the following files: - -**File to edit:** +Edit the version constant in: ``` src/core/Config/AppConfig.php ``` -**Auto-update command:** +**Quick command:** ```bash sed -i "s/define('XC_VM_VERSION', *'[0-9]\+\.[0-9]\+\.[0-9]\+');/define('XC_VM_VERSION', 'X.Y.Z');/" src/core/Config/AppConfig.php ``` -**Commit the changes with a message:** +**Commit:** ```bash -git add . +git add src/core/Config/AppConfig.php git commit -m "Bump version to X.Y.Z" git push ``` -> 💡 **Tip:** Replace `X.Y.Z` with the actual version, e.g., `1.2.3`. +> 💡 Replace `X.Y.Z` with the actual version. --- -## 🧹 2. Deleted Files +## 🧹 2. Deleted Files (Automated) -* Generate a list of deleted files: +File cleanup is **fully automated**. No manual steps required. + +**How it works:** + +1. `make main_update` / `make lb_update` internally runs `make delete_files_list` +2. This generates `dist/migrations/deleted_files.txt` (diff of deleted files since last tag) +3. The file is packed into the update archive at `migrations/deleted_files.txt` +4. During `php console.php update post-update`, `MigrationRunner::runFileCleanup()` reads it and deletes the listed files automatically + +> ⚠️ **Review only:** After building, inspect `dist/migrations/deleted_files.txt` to verify no critical files are listed by mistake. + +--- + +## 🧪 3. Pre-Release Validation + +Before publishing, verify the build works: + +**PHP syntax check:** ```bash -make delete_files_list +make syntax_check ``` -* Open the file `dist/deleted_files.txt`. -* Copy the contents to `src/cli/Commands/UpdateCommand.php` in the `$rCleanupFiles` array inside the `post-update` case. - -> ⚠️ **Important:** Ensure paths are correct to avoid deleting critical files. - -**Commit changes with a message:** +**Docker test install** (see `tools/test-install/`): ```bash -git add . -git commit -m "Added deletion of old files before release" -git push +cd tools/test-install +docker compose up -d --build +docker exec -it xc_test bash /opt/auto_install.sh +``` + +> ✅ Verify the panel loads at `http://localhost:8880` and admin login works. + +**Security scan** (runs automatically on push via `.github/workflows/security-scan.yml`): + +```bash +tools/php_syntax_check.sh +tools/run_scan.sh ``` --- -## ⚙️ 3. Build Archives +## ⚙️ 4. Build Archives -> 🤖 **Automated:** Building is handled by GitHub Actions workflow `.github/workflows/build-release.yml` when a release is published. Assets are automatically attached to the release. +> 🤖 **Production builds** are handled by GitHub Actions (`.github/workflows/build-release.yml`) when a release is published. Assets are attached automatically. -For **local builds**, run the following commands: +**For local builds:** ```bash make new @@ -83,19 +104,25 @@ make lb_update After building, `dist/` should contain: - - `loadbalancer.tar.gz` — LB installation archive - - `loadbalancer_update.tar.gz` — LB update archive - - `XC_VM.zip` — MAIN installation archive - - `update.tar.gz` — MAIN update archive - - `hashes.md5` — file with checksums +| File | Description | +|------|-------------| +| `XC_VM.zip` | MAIN installation archive | +| `update.tar.gz` | MAIN update archive | +| `loadbalancer.tar.gz` | LB installation archive | +| `loadbalancer_update.tar.gz` | LB update archive | +| `hashes.md5` | MD5 checksums | -> 🧰 **Check:** After building, verify archive integrity with `md5sum -c hashes.md5`. +**Verify integrity:** + +```bash +cd dist && md5sum -c hashes.md5 +``` --- -## 📝 4. Changelog +## 📝 5. Changelog -Fetch the previous release tag via GitHub API and generate the changelog: +**Generate commit log:** ```bash PREV_TAG=$(curl -s https://api.github.com/repos/Vateron-Media/XC_VM/releases/latest \ @@ -104,40 +131,43 @@ echo "Previous release: $PREV_TAG" git log --pretty=format:"- %s (%h)" "$PREV_TAG"..main > dist/changes.md ``` -* **Then add current release changes** using this JSON: - -[https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json](https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json) - -* Add current release changes in JSON format: +**Update the public changelog** at: +[XC_VM_Update/changelog.json](https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json) ```json -[ - { - "version": "X.Y.Z", - "changes": [ - "Description of change 1", - "Description of change 2" - ] - } -] +{ + "version": "X.Y.Z", + "changes": [ + "Description of change 1", + "Description of change 2" + ] +} ``` -> 💬 **Recommendation:** Keep descriptions concise and informative, focusing on key improvements and fixes. +> 💬 Keep descriptions concise — focus on user-facing improvements and fixes. --- -## 🚀 5. GitHub Release +## 🚀 6. GitHub Release -* Create a new release on [GitHub Releases](https://github.com/Vateron-Media/XC_VM/releases) **without attaching files**. -* Include the changelog in the release description. -* After publishing, GitHub Actions will automatically build and attach: +1. Go to [GitHub Releases](https://github.com/Vateron-Media/XC_VM/releases) +2. Create a new release with tag `X.Y.Z` +3. Paste the changelog as the release description +4. Publish **without attaching files** — GitHub Actions will build and attach them - - `loadbalancer.tar.gz` — LB installation archive - - `loadbalancer_update.tar.gz` — LB update archive - - `XC_VM.zip` — MAIN installation archive - - `update.tar.gz` — MAIN update archive - - `hashes.md5` — file with checksums +After publishing, the workflow will automatically: +* Build all 4 archives + checksums +* Attach them to the release +* Send a Telegram notification via `release-notifier.yml` -> ✅ **Completion:** Wait for the workflow to finish (Actions tab), then verify that all files are downloadable and checksums match. +> ✅ Wait for the Actions workflow to finish, then verify all files are downloadable. ---- \ No newline at end of file +--- + +## 📢 7. Post-Release + +* [ ] Verify all 5 assets are attached to the release +* [ ] Run `md5sum -c hashes.md5` on downloaded files +* [ ] Check Telegram notification was sent +* [ ] Update `changelog.json` in `XC_VM_Update` repo if not done yet +* [ ] Close related GitHub issues/milestones diff --git a/docs/ru/updates_checklist.md b/docs/ru/updates_checklist.md index a16f625..94253a8 100644 --- a/docs/ru/updates_checklist.md +++ b/docs/ru/updates_checklist.md @@ -1,7 +1,7 @@ # ✅ Чеклист подготовки релиза XC_VM- В этом документе описан процесс создания релиза XC_VM — пошаговое руководство для разработчиков по обновлению версии, сборке архивов и публикации на GitHub. + Пошаговое руководство по подготовке и публикации релиза XC_VM.
--- @@ -9,69 +9,89 @@ ## 📚 Навигация - [🔢 1. Обновить версию](#1-обновить-версию) -- [🧹 2. Удалённые файлы](#2-удалённые-файлы) -- [⚙️ 3. Сборка архивов](#3-сборка-архивов) -- [📝 4. Changelog](#4-changelog) -- [🚀 5. GitHub релиз](#5-github-релиз) +- [🧹 2. Удалённые файлы (автоматически)](#2-удалённые-файлы-автоматически) +- [🧪 3. Предрелизная проверка](#3-предрелизная-проверка) +- [⚙️ 4. Сборка архивов](#4-сборка-архивов) +- [📝 5. Changelog](#5-changelog) +- [🚀 6. GitHub релиз](#6-github-релиз) +- [📢 7. После релиза](#7-после-релиза) --- ## 🔢 1. Обновить версию -* Установить **новое значение `XC_VM_VERSION`** в следующих файлах: - -**Файл для редактирования:** +Изменить константу версии в: ``` src/core/Config/AppConfig.php ``` -**Auto-update команда:** +**Быстрая команда:** ```bash sed -i "s/define('XC_VM_VERSION', *'[0-9]\+\.[0-9]\+\.[0-9]\+');/define('XC_VM_VERSION', 'X.Y.Z');/" src/core/Config/AppConfig.php ``` -**Закоммитить изменения с сообщением:** +**Закоммитить:** ```bash -git add . +git add src/core/Config/AppConfig.php git commit -m "Bump version to X.Y.Z" git push ``` -> 💡 **Совет:** Замените `X.Y.Z` на актуальную версию, например, `1.2.3`. +> 💡 Замените `X.Y.Z` на актуальную версию. --- -## 🧹 2. Удалённые файлы +## 🧹 2. Удалённые файлы (автоматически) -* Выполнить команду для генерации списка удаленных файлов: +Очистка файлов **полностью автоматизирована**. Ручных шагов не требуется. - ```bash - make delete_files_list - ``` +**Как это работает:** +1. `make main_update` / `make lb_update` внутри вызывает `make delete_files_list` +2. Генерируется `dist/migrations/deleted_files.txt` (diff удалённых файлов с последнего тега) +3. Файл упаковывается в архив обновления как `migrations/deleted_files.txt` +4. При `php console.php update post-update` вызывается `MigrationRunner::runFileCleanup()`, который автоматически удаляет перечисленные файлы -* Открыть файл `dist/deleted_files.txt`. -* Скопировать содержимое в `src/cli/Commands/UpdateCommand.php` в массив `$rCleanupFiles` внутри фазы `post-update`. +> ⚠️ **Только проверка:** после сборки просмотрите `dist/migrations/deleted_files.txt` — убедитесь, что в списке нет критичных файлов. -> ⚠️ **Важно:** Убедитесь, что пути указаны корректно, чтобы избежать удаления важных файлов. +--- -**Закоммитить изменения с сообщением:** +## 🧪 3. Предрелизная проверка + +Перед публикацией убедитесь, что сборка работает: + +**Проверка синтаксиса PHP:** ```bash -git add . -git commit -m "Added deletion of old files before release" -git push +make syntax_check +``` + +**Тестовая установка в Docker** (см. `tools/test-install/`): + +```bash +cd tools/test-install +docker compose up -d --build +docker exec -it xc_test bash /opt/auto_install.sh +``` + +> ✅ Убедитесь, что панель открывается по `http://localhost:8880` и вход в админку работает. + +**Security-сканирование** (запускается автоматически при push через `.github/workflows/security-scan.yml`): + +```bash +tools/php_syntax_check.sh +tools/run_scan.sh ``` --- -## ⚙️ 3. Сборка архивов +## ⚙️ 4. Сборка архивов -> 🤖 **Автоматически:** Сборка выполняется через GitHub Actions workflow `.github/workflows/build-release.yml` при публикации релиза. Файлы автоматически прикрепляются к релизу. +> 🤖 **Production-сборки** выполняются через GitHub Actions (`.github/workflows/build-release.yml`) при публикации релиза. Файлы прикрепляются автоматически. -При необходимости **локальной сборки** выполните команды: +**Для локальной сборки:** ```bash make new @@ -81,19 +101,27 @@ make main_update make lb_update ``` -После сборки в директории `dist/` должны быть: +После сборки в `dist/` должны быть: - - `loadbalancer.tar.gz` — установочный архив LB - - `loadbalancer_update.tar.gz` — архив обновления LB - - `XC_VM.zip` — установочный архив MAIN - - `update.tar.gz` — архив обновления MAIN - - `hashes.md5` — файл с хеш-суммами +| Файл | Описание | +|------|----------| +| `XC_VM.zip` | Установочный архив MAIN | +| `update.tar.gz` | Архив обновления MAIN | +| `loadbalancer.tar.gz` | Установочный архив LB | +| `loadbalancer_update.tar.gz` | Архив обновления LB | +| `hashes.md5` | Контрольные суммы MD5 | + +**Проверка целостности:** + +```bash +cd dist && md5sum -c hashes.md5 +``` --- -## 📝 4. Changelog +## 📝 5. Changelog -Получите тег предыдущего релиза через GitHub API и сгенерируйте changelog: +**Сгенерировать лог коммитов:** ```bash PREV_TAG=$(curl -s https://api.github.com/repos/Vateron-Media/XC_VM/releases/latest \ @@ -102,39 +130,43 @@ echo "Предыдущий релиз: $PREV_TAG" git log --pretty=format:"- %s (%h)" "$PREV_TAG"..main > dist/changes.md ``` -* **Перейдите по ссылке и добавьте изменения текущего релиза:** - [https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json](https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json) +**Обновить публичный changelog** по ссылке: +[XC_VM_Update/changelog.json](https://github.com/Vateron-Media/XC_VM_Update/blob/main/changelog.json) -* Добавить изменения текущего релиза в формате JSON: +```json +{ + "version": "X.Y.Z", + "changes": [ + "Описание изменения 1", + "Описание изменения 2" + ] +} +``` - ```json - [ - { - "version": "X.Y.Z", - "changes": [ - "Описание изменения 1", - "Описание изменения 2" - ] - } - ] - ``` - -> 💬 **Рекомендация:** Держите описания изменений краткими и информативными, фокусируясь на ключевых улучшениях и фиксах. +> 💬 Описания должны быть краткими — фокус на пользовательских улучшениях и исправлениях. --- -## 🚀 5. GitHub релиз +## 🚀 6. GitHub релиз -* Создать новый релиз на [GitHub Releases](https://github.com/Vateron-Media/XC_VM/releases) **без прикрепления файлов**. -* Указать changelog в описании релиза. -* После публикации GitHub Actions автоматически соберёт и прикрепит к релизу: +1. Перейти на [GitHub Releases](https://github.com/Vateron-Media/XC_VM/releases) +2. Создать новый релиз с тегом `X.Y.Z` +3. Вставить changelog в описание релиза +4. Опубликовать **без прикрепления файлов** — GitHub Actions соберёт и прикрепит их - - `loadbalancer.tar.gz` — установочный архив LB - - `loadbalancer_update.tar.gz` — архив обновления LB - - `XC_VM.zip` — установочный архив MAIN - - `update.tar.gz` — архив обновления MAIN - - `hashes.md5` — файл с хеш-суммами +После публикации workflow автоматически: +- Соберёт все 4 архива + контрольные суммы +- Прикрепит их к релизу +- Отправит Telegram-уведомление через `release-notifier.yml` -> ✅ **Завершение:** Дождитесь завершения workflow (вкладка Actions) и проверьте, что все файлы доступны для скачивания и хеш-суммы совпадают. +> ✅ Дождитесь завершения Actions и проверьте, что все файлы доступны для скачивания. ---- \ No newline at end of file +--- + +## 📢 7. После релиза + +- [ ] Проверить, что все 5 файлов прикреплены к релизу +- [ ] Скачать и проверить `md5sum -c hashes.md5` +- [ ] Убедиться, что Telegram-уведомление отправлено +- [ ] Обновить `changelog.json` в репозитории `XC_VM_Update` (если ещё не сделано) +- [ ] Закрыть связанные GitHub issues/milestones