MeshVault/CONTRIBUTING.md

Contributing to MeshVault

Setup and checks

Host requirements: Docker Compose v2+ with Linux containers. No host PHP, Composer or Node is required.

# Start the stack (builds images if needed)
./dev.sh up
# Or on Windows: .\dev.ps1 up

# Run checks inside containers
./dev.sh test
./dev.sh lint

# Build assets deterministically
./dev.sh assets
# Watch during development
./dev.sh watch

If you have PHP 8.3+ and Composer 2 locally, you can also run:

composer install --no-interaction
composer validate --strict
composer lint
composer test

Commit both composer.lock and package-lock.json for reproducible builds. migrate and seed are unavailable until M2 (#12); they exit nonzero and leave #10 open. Never remove volumes with down -v; the wrapper forbids it.

composer lint enforces PSR-12 on PHP in src, public, config, bin, templates, db/migrations and tests. composer test runs foundation checks and PHPUnit unit/integration tests. Add behavior and regression tests with each implementation.

Conventions

• PHP: PSR-12, four spaces, LF, UTF-8 without BOM, final newline, no closing PHP tag in PHP-only files. Use strict types in new PHP source files.
• Use MeshVault as the future application namespace; PascalCase classes and file names, camelCase methods/variables, UPPER_SNAKE_CASE constants. PSR-4 wiring is M1.
• Database: plural snake_case tables, snake_case columns, id primary keys and singular _id foreign keys. Use UTC for stored application timestamps; distinguish added_at from file mtime. Parameterize SQL and version schema changes.
• Keep domain/services, persistence and HTTP rendering separate. Validate at boundaries, escape rendered values and protect state-changing requests against CSRF.
• Never infer file deletion from catalog removal. Restrict physical operations to configured managed roots; preserve source files, and test rollback/recovery paths.
• Do not introduce a framework, runtime dependency or storage behavior without documenting its choice in the relevant issue.

Workflow

1. Choose an issue and check its dependencies; milestones group outcomes, not a strict schedule. In particular, repository service #28 precedes worker #25.
2. Use branches such as feature/20-import-scan, fix/47-missing-file or docs/5-contributing.
3. Keep changes focused and include tests and documentation. Test failure paths for filesystem operations as well as the successful path.
4. Use type: concise imperative description commits, such as docs: document managed-storage semantics or test: cover hash mismatch. Types include feat, fix, docs, test, refactor, build and chore. Existing history used emoji-prefixed messages; new commits need no emoji.
5. Include issue references, commands/results, limitations and migration/storage effects in the review description. Do not close implementation issues before their acceptance criteria are verified and the work is committed/reviewable.

Never commit credentials, dependencies, generated assets, library contents or PostgreSQL data. notes/ and .superpowers/ are local-only planning storage. Contributions are under AGPL-3.0-only, the project license.