# 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):

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

2. Run unit tests and static analysis:

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

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

```bash
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):

```bash
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:

```bash
php -S 127.0.0.1:8000 -t tests/smoke/public -d auto_prepend_file=$(pwd)/uploadshield.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.