76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# Contributing to MeshVault
|
|
|
|
## Setup and checks
|
|
|
|
Host requirements: Docker Compose v2+ with Linux containers. No host PHP,
|
|
Composer or Node is required.
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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 available via `./dev.sh` (M2 #12). 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.
|