Startup

doc/CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Contribution & Code Style Guide
+
+This document is for Junie (and humans) to keep our code style consistent and to quickly find the files we’ll reference during development of the Online Escape Room platform.
+
+Project type: Symfony 7.3, PHP >= 8.2, Doctrine ORM 3, Twig, Stimulus (UX), Importmap/Asset Mapper, PHPUnit 11.
+
+
+## 1. Repository Conventions
+- PHP version: 8.2+ (composer.json enforces ">=8.2").
+- Framework: Symfony 7.3.* (see composer.json).
+- Architecture: MVC with Controllers in `src/Controller`, Entities in `src/Entity`, Repositories in `src/Repository`, Templates in `templates`.
+- Env files: `.env`, `.env.local` (ignored), and environment overrides like `.env.test.local`.
+- Routes: annotation/attributes in controllers or YAML/PHP in `config/routes`.
+- Documentation location: All documentation must live under the `doc/` directory. New docs requested by the team will be added there.
+
+
+## 2. Coding Standards
+
+### 2.1 PHP
+- Standard: PSR-12 (line length soft cap 120; prefer multi-line for long signatures/arrays).
+- Strict types at top of new files: `declare(strict_types=1);`
+- Type-hint everything (params, returns, properties). Prefer readonly where applicable.
+- Visibility: declare on all properties and methods.
+- Exceptions: throw domain-specific exceptions for game logic; do not return null where an exception is appropriate.
+- Controllers: keep thin; delegate to services. Use DTOs/Form types to validate input.
+- Dependency Injection: constructor injection; avoid container-aware services.
+- Naming: Services suffixed with `...Service`, commands with `...Command`, event listeners with `...Listener`/`...Subscriber`.
+- Logging: use `Psr\Log\LoggerInterface` where meaningful.
+
+### 2.2 Twig
+- Keep templates lean; no heavy logic. Use filters/functions and view models if needed.
+- Use `trans` for strings that will be localized.
+- Partial templates/components: place in `templates/_partials` or `templates/components`.
+
+### 2.3 JavaScript (Stimulus / vanilla)
+- Use ES modules via Importmap/Asset Mapper.
+- Controllers in `assets/controllers`. Name as `something_controller.js` following Stimulus conventions.
+- Prefer small, focused controllers. Keep DOM queries scoped to controller element.
+- Avoid global state; communicate via events or Turbo streams when appropriate.
+
+### 2.4 Styles (CSS/SCSS)
+- Keep styles in `assets/styles`. Use BEM naming for classes.
+- Prefer CSS variables for theme colors, spacing scale, z-index scale.
+
+### 2.5 YAML / Config
+- 2-space indentation, no tabs.
+- Use parameters and env vars (`env()`) instead of hardcoding secrets.
+
+### 2.6 Git & Commits
+- Branch naming: `feature/<short-name>`, `fix/<short-name>`, `chore/<short-name>`.
+- Commit messages:
+  - Conventional commits style: `feat: ...`, `fix: ...`, `chore: ...`, `docs: ...`, `test: ...`, `refactor: ...`.
+  - First line ≤ 72 chars; add body when needed with rationale.
+
+
+## 3. Linting, Tests, and Quality
+
+### 3.1 PHP
+- Use PHP-CS-Fixer or PHP_CodeSniffer (PHPCS) with PSR-12. If not yet installed, proposed composer scripts (to add later):
+  - `composer require --dev friendsofphp/php-cs-fixer`
+  - Script: `php-cs-fixer fix --allow-risky=yes`
+- Static analysis: PHPStan level 6–8 recommended:
+  - `composer require --dev phpstan/phpstan`
+  - Run: `vendor/bin/phpstan analyse src tests` (configure `phpstan.neon` later)
+
+### 3.2 Symfony
+- Cache and debug:
+  - `php bin/console cache:clear`
+  - `php bin/console debug:router`
+  - `php bin/console debug:container`
+
+### 3.3 Tests
+- PHPUnit (already required):
+  - Run tests: `vendor/bin/phpunit`
+  - Tests location: `tests/`
+  - Config: `phpunit.dist.xml`
+
+### 3.4 Frontend
+- Stimulus/UX: controllers auto-registered via `symfony/stimulus-bundle`.
+- Asset Mapper/Importmap:
+  - Install deps: `php bin/console importmap:install`
+  - Dev server (if using symfony local server): `symfony server:start -d`
+
+
+## 4. Project File Map (Quick Reference)
+- App kernel: `src/Kernel.php`
+- Controllers: `src/Controller/`
+- Domain entities: `src/Entity/`
+- Repositories: `src/Repository/`
+- Migrations: `migrations/`
+- Templates: `templates/`
+- Translations: `translations/`
+- Assets entry: `assets/app.js`, styles in `assets/styles/`
+- Stimulus controllers: `assets/controllers/`
+- Routes: `config/routes/`
+- Packages config: `config/packages/`
+- Env vars: `.env` (base), `.env.local` (local overrides)
+- Public web root: `public/`
+- Tests: `tests/`
+
+
+## 5. How We Build Features (Checklist)
+1) Create branch: `feature/<name>`.
+2) Describe the task in an issue with acceptance criteria.
+3) Implement backend (entities/services/controllers) with tests.
+4) Implement templates and Stimulus controller if interactive.
+5) Add/adjust routes and translations.
+6) Run: linters, phpstan, phpunit; ensure green.
+7) Open PR; request review.
+
+
+## 6. Escape Room Domain Notes (early)
+- Core concepts likely: Game, Room, Puzzle, Session, Player, Team, Hint, Timer.
+- Consider events (Domain Events) for puzzle solved, hint requested, time warnings.
+- Real-time collaboration options: Symfony Mercure, WebSockets, or Turbo Streams.
+- Persist immutable audit trail for gameplay.
+
+
+## 7. Editor Configuration
+- Recommend EditorConfig. If we add `.editorconfig` later, set:
+  - Indent 4 spaces for PHP, 2 for YAML/Twig/JS/CSS.
+  - LF line endings, UTF-8, insert final newline, trim trailing whitespace.
+
+
+## 8. Security & Secrets
+- Never commit secrets. Use environment variables or Symfony Vault.
+- Review `APP_ENV`, `APP_SECRET`, database DSN in `.env` and `.env.local`.
+
+
+## 9. Release & Environments
+- Envs: `dev`, `test`, `prod`.
+- Build steps: run migrations, warmup cache, compile assets if using.
+
+
+## 10. References
+- Symfony Best Practices: https://symfony.com/doc/current/best_practices.html
+- Doctrine ORM 3 Docs: https://www.doctrine-project.org/projects/doctrine-orm/en/current/
+- Stimulus: https://stimulus.hotwired.dev/