mirror of https://github.com/Vateron-Media/XC_VM.git synced 2026-09-27 04:01:57 +02:00

Files

T

Divarion-D 9bf4e98556 docs(contributing): document make phpstan and baseline workflow

Adds a Static Analysis section: how to run PHPStan, that CI fails only on new
issues (committed baseline), not to grow the baseline to hide real problems,
how to regenerate it, and the clear-result-cache caveat after stub/PHPDoc edits.

2026-06-23 22:07:31 +03:00

5.2 KiB

Raw Blame History

Contributing to the Project

Thank you for considering contributing to this project! Follow these guidelines to make the process smooth for everyone.

📌 General Guidelines

Minimally use AI
Follow the project's coding style and best practices.
Ensure your changes are well-documented.
Write meaningful commit messages.
Keep pull requests focused on a single change.
If you are refactoring and are not sure if the code is unused elsewhere, comment it out. It will be removed after the release.

🛠️ Installation

To install the panel, follow these steps:

Update system

sudo apt update && sudo apt full-upgrade -y

Install dependencies
```
sudo apt install -y python3-pip unzip
```

Download latest release

latest_version=$(curl -s https://api.github.com/repos/Vateron-Media/XC_VM/releases/latest | grep '"tag_name":' | cut -d '"' -f 4)
wget "https://github.com/Vateron-Media/XC_VM/releases/download/${latest_version}/XC_VM.zip"

Unpack and install
```
unzip XC_VM.zip
sudo python3 install
```

✨ Code Standards

Use K&R coding style for PHP.
Follow best practices for Python and Bash scripts.
Avoid unused functions and redundant code.

🔍 Pre-Commit Checks

Before committing, run the PHP syntax checker:

bash tools/php_syntax_check.sh

This is the same check that CI runs. You can also check a single file:

bash tools/php_syntax_check.sh src/domain/Device/EnigmaService.php

Do not submit PRs with syntax errors — CI will reject them.

🔬 Static Analysis (PHPStan)

The project is analysed with PHPStan (level 5). There is no Composer — the pinned PHAR is downloaded on first run, and a bootstrap registers the project's constants/classes (tools/phpstan/).

Run the analysis before submitting a PR:

make phpstan

This is the same check CI runs. It must report [OK] No errors.

How the gate works:

A committed baseline (phpstan-baseline.neon) freezes the pre-existing findings, so CI only fails on new issues your change introduces — fix those before pushing.
The baseline is not a list of accepted bugs (most entries are false positives from dynamic DB-row shapes or templates). Do not grow it to hide a real problem in new code.
If you fix a batch of existing findings, regenerate the (smaller) baseline:
```
make phpstan-baseline
```
After editing tools/phpstan/constants.stub.php or any PHPDoc types, clear the result cache first: php tools/phpstan/phpstan.phar clear-result-cache.

🧪 Adding Tests

Add new PHP tests under tests/Unit/.
Prefer focused tests for the class or file you changed instead of broad project-wide mock coverage.
Name test files after the target class, for example GitHubReleasesTest.php.
Cover real behavior: valid inputs, invalid inputs, edge cases, and side effects.
If the code writes to stdout, capture output inside the test so PHPUnit output stays readable.

Run a single test file while developing:

/home/xc_vm/bin/php/bin/php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist tests/Unit/GitHubReleasesTest.php

Show which test is executing now:

/home/xc_vm/bin/php/bin/php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist --debug --no-progress

Run the default targeted unit suite before submitting a PR:

/home/xc_vm/bin/php/bin/php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist

🔥 Submitting a Pull Request

Fork the repository and create a new branch:
```
git checkout -b feature/your-feature
```

Make your changes and commit them:

git commit -m "Add feature: description"

Push your branch:
```
git push origin feature/your-feature
```
Open a pull request on GitHub.

Code Reviews

All PRs must be reviewed by at least 2 maintainers. Address review comments before merging.

🚀 Reporting Issues

Use GitHub Issues to report bugs and suggest features.
Provide clear steps to reproduce issues.
Attach relevant logs or error messages.

🔀 Branch Naming Conventions

To maintain a clean and organized repository, follow these branch naming conventions:

Title	Template	Example
Features	`feature/<short-description>`	`feature/user-authentication`
Bug Fixes	`fix/<short-description>`	`fix/login-bug`
Hotfixes	`hotfix/<short-description>`	`hotfix/critical-error`
Refactoring	`refactor/<short-description>`	`refactor/code-cleanup`
Testing	`test/<short-description>`	`test/api-endpoints`
Documentation	`docs/<short-description>`	`docs/documentation-api`

🌟 Recognition

Your GitHub profile will be added to CONTRIBUTORS.md

Thank you for contributing! 🎉

5.2 KiB Raw Blame History