# Contributing to Quaeriva

Thanks for helping improve Quaeriva. Keep changes focused, reviewable, and compatible with ordinary PHP shared hosting.

## Project constraints

- PHP 8.1+, PDO MySQL, vanilla PHP/HTML/CSS/JavaScript.
- Do not introduce a required Composer, Node.js, Redis, WebSocket, or hosted runtime service without an accepted architectural change.
- Preserve arbitrary `APP_BASE_URL` root/subdirectory deployment; never hard-code the project folder into internal links.
- Preserve the language registry, Arabic/English source packs, registered additional languages, RTL/LTR logical CSS, and `utf8mb4` storage.
- New source UI strings must exist in both shipped base packs.
- Interface locale and content locale are separate concerns.
- Never commit `config/database.local.php`, `.env`, installation locks, database dumps, logs, API tokens, Telegram credentials, or other secrets.

## Database migrations

Migrations are forward-only and tracked in `schema_migrations`. Never edit or renumber a migration that may already be installed. New schema work after 0.7.0 starts after `018_create_audit_moderation.sql`.

A migration upgrading an existing partial table must check for existing columns/indexes where necessary instead of assuming a fresh database.

## Development workflow

1. Write or update the focused failing test for changed behavior.
2. Make the smallest implementation that satisfies the contract.
3. Run the focused test and PHP lint.
4. Run related non-database suites.
5. For persistence changes, run the MySQL-backed suites against a disposable database.
6. Run `php bin/admin-smoke.php --write` when administration persistence changes.
7. Update `CHANGELOG.md` and user/developer documentation for visible behavior.

Useful commands:

```text
php bin/run-all-tests.php
php bin/run-all-tests.php --strict   # CI: zero skips allowed
php bin/migrate.php
php bin/doctor.php
php bin/admin-smoke.php --write
php tests/Release/task27.php
php tests/Release/task28.php
```

GitHub Actions runs every test file against MySQL on the project PHP matrix with `--strict`. A local run may report database suites as SKIP when `pdo_mysql` is unavailable; a release tag may not. Do not tag a release whose database-backed CI is red or skipped.

## Security review

- Browser mutations use CSRF.
- Authorization is enforced server-side, not by hidden buttons alone.
- User-controlled SQL values use prepared statements.
- User output is escaped; allowed HTML is sanitized.
- Raw passwords/tokens/secrets are never logged or returned after one-time creation.
- Sensitive administration/API-token changes should create audit evidence.
- Error responses must not expose traces or database credentials in production.

## UI and accessibility review

- Use logical CSS properties rather than left/right assumptions.
- Test Arabic RTL and English LTR; registered fallback languages must not leak translation keys.
- Search controls follow UI direction, user-content controls may use `dir="auto"`, and technical values remain readable LTR where appropriate.
- Tables must remain usable on mobile through responsive overflow.
- Keep labels, focus states, error states, empty states, and keyboard interaction intact.