XC_VM/docs/en/builds/updates_checklist.md

XC_VM Release Preparation Checklist

Step-by-step guide for preparing and publishing an XC_VM release.

---

1. Changelog

Generate commit log (work commits only):

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 is required: dist/ does not exist on a fresh clone and make new wipes it — without it the redirect fails with "No such file or directory".

Update changelog.json in the repository root — this file contains only the changes for the upcoming release:

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

The panel fetches this file from the release tag automatically via GithubReleases::getChangelog().

💬 Keep descriptions concise — focus on user-facing improvements and fixes.

---

2. Prepare Release Baseline

First, finish all feature/fix/docs work and make sure it is already in main.

Set the version variable once and reuse it in all commands below:

VERSION="X.Y.Z"

⚠️ Do not create a separate version-bump commit/push at this step. Otherwise dist/changes.md will include extra release commits and force additional edits.

---

3. Deleted Files

Before building, generate the list of files to delete on update:

make generate_deleted_files

This runs git diff between LAST_TAG and HEAD, extracts deleted files under src/, strips the src/ prefix, and writes the result to src/migrations/deleted_files.txt.

If LAST_TAG cannot be auto-detected (no network / no releases), pass it explicitly:

make generate_deleted_files LAST_TAG=1.2.16

Review the generated file — verify no critical files are listed by mistake:

cat src/migrations/deleted_files.txt

After validation, make main / make lb will pack the file into the archive via delete_files_list / lb_delete_files_list.

During php console.php update post-update, MigrationRunner::runFileCleanup() reads it and deletes the listed files automatically.

⚠️ Lines starting with # are comments and will be ignored. You can comment out files you want to keep.

---

4. Pre-Release Validation

Before publishing, verify the build works:

Quality checks (CI runs the same set on the tag — confirm it is green):

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/

ℹ️ The Docker test install moved to step 6 — it requires a built dist/XC_VM.zip.

Security scan: runs automatically on push/PR via .github/workflows/security-scan.yml (Semgrep) — no manual step.

---

5. Update Version and Create a Single Release Commit

Edit the version constant, disable the phpMiniAdmin access flag, and clear its password in:

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 commit -m "Prepare release ${VERSION}"
git push

⚠️ This removes the need for multiple release commits.

---

6. Build Archives

🤖 Production builds are handled by GitHub Actions (.github/workflows/build-release.yml) when a release is published. Assets are attached automatically.

For local builds:

make new
make lb
make main

After building, dist/ should contain:

File	Description
XC_VM.zip	MAIN installer (install script + xc_vm.tar.gz)
xc_vm.tar.gz	MAIN archive (install & update)
loadbalancer.tar.gz	LB archive (install & update)
hashes.md5	MD5 checksums

The same archive is used for both clean installation and updates. The update script (src/update) filters out binary/config directories at runtime using the hardcoded UPDATE_EXCLUDE_DIRS list inside the Python script itself.

Verify integrity:

cd dist && md5sum -c hashes.md5

Docker test install (see tools/test-install/) — only after building, since it needs dist/XC_VM.zip:

bash tools/test-install/test_release.sh

This builds the image, starts the container with systemd, and runs the installer automatically. dist/XC_VM.zip is mounted into the container as a read-only volume.

✅ Verify the panel loads at http://localhost:8880 and admin login works.

---

7. GitHub Release

1. Go to GitHub Releases
2. Create a new release with the tag from the first step
3. Paste the changelog as the release description
4. Publish without attaching files — GitHub Actions will build and attach them

After publishing, the workflow will automatically:

• Build all archives + checksums
• Attach them to the release
• Send a Telegram notification via release-notifier.yml

✅ Wait for the Actions workflow to finish, then verify all files are downloadable.

---

8. Post-Release

• Verify all 4 assets are attached to the release
• Run md5sum -c hashes.md5 on downloaded files
• Check Telegram notification was sent
• Close related GitHub issues/milestones

---

Command Reference

Every make target used during release prep, in one place.

Quality checks — run make dev-tools first, make dev-clean when done:

Command	Purpose
make dev-tools	Install dev tooling (PHPStan, PHP-CS-Fixer) via composer install
make phpstan	Static analysis (also catches syntax errors)
make phpstan-baseline	Regenerate the PHPStan baseline
make cs	Code-style check — import/namespace hygiene (PHP-CS-Fixer, dry-run)
make cs-fix	Apply code-style fixes in place
make gates	PSR-4 regression gates (procedural-use, LB-archive, vendor-prod-only)
make dev-clean	Remove the dev tools again, restoring the production-only vendor/
php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist	Unit tests

Release prep & build:

Command	Purpose
make generate_deleted_files	Regenerate src/migrations/deleted_files.txt
make new	Reset the dist/ output directory (run before building)
make lb	Build the LoadBalancer archive into dist/
make main	Build the MAIN archive into dist/
bash tools/test-install/test_release.sh	Docker install test of the built release