UploadShied/CONTRIBUTING.md

Contributing

Thanks for contributing! This document explains how to run tests, linting, and the suggested workflow for changes.

Quick dev setup

1. Install dependencies (developer machine):

git clone <repo-url> /path/to/uploadshield
cd /path/to/uploadshield
composer install --no-interaction --prefer-dist

2. Run unit tests and static analysis:

vendor/bin/phpunit --configuration phpunit.xml
vendor/bin/phpstan analyse -c phpstan.neon

3. Run PHP lint across the project (example):

find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l

Branching & PR workflow

• Create a feature branch from main (or master if your repo uses it):

git checkout -b feature/short-description

• Make small, focused commits with clear messages. Example:

Add CONFIG_REFERENCE.md mapping configuration options

• Push and open a pull request to main. Provide a short description of the change and mention testing steps.

Tests and CI

• The repository uses GitHub Actions to run PHPUnit and PHPStan on supported PHP versions. Ensure tests pass locally before opening a PR.
• If you add new functionality, provide unit tests in tests/ and update phpunit.xml if needed.

Smoke tests

• A basic smoke harness exists under tests/smoke/. To run locally:

php -S 127.0.0.1:8000 -t tests/smoke/public -d auto_prepend_file=$(pwd)/upload-logger.php
# then POST files with curl or a test client

Coding style

• Keep changes minimal and consistent with existing code. Avoid reformatting unrelated files.
• Follow PSR-12 style where practical for new PHP code.

Adding docs

• For user-facing changes, update README.md, docs/INSTALLATION.md and INTEGRATION.md accordingly. Prefer short, copy-paste examples for operators.

Security disclosures

• If you find a security vulnerability, do not open a public issue. Contact maintainers privately and include reproduction steps.

Contact

• Open an issue or a PR on GitHub; maintainers will review and respond.

Thank you for helping improve UploadShield.