75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
OpenSem builds on Laravel 9.
|
|
|
|
Core application code lives in `app/`, while HTTP routes reside in
|
|
`routes/` and Blade views in `resources/views/`. Reusable front-end
|
|
assets (JS, SCSS, images) sit under `resources/` and are compiled into
|
|
`public/` via Laravel Mix.
|
|
|
|
Database blueprints are versioned in `database/migrations/` with seeds
|
|
in `database/seeders/`.
|
|
|
|
Tests are organised in `tests/Unit/` and `tests/Feature/`; keep large
|
|
fixtures in `tests/Fixtures/` to avoid polluting source directories.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `composer install` — install PHP dependencies defined in
|
|
`composer.json`.
|
|
|
|
- `php artisan serve` — start a local HTTP server on port 8000.
|
|
|
|
- `npm install && npm run dev` — install Node tooling and build UI
|
|
assets for development.
|
|
|
|
- `npm run prod` — generate minified production assets in `public/`.
|
|
|
|
- `php artisan migrate --seed` — apply database schema and load
|
|
default data for demo instances.
|
|
|
|
- `./build.sh` — builds a `.tar.xz` that contains the production and
|
|
deployement ready source to be deployed.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Follow PSR-12 with four-space indentation and `snake_case` database
|
|
columns. Controllers, models, and Livewire components use StudlyCase
|
|
class names; private methods remain `camelCase`. Run `composer run
|
|
inspect` before opening a PR to execute `phpcs` and `phpstan`. For
|
|
front-end changes, keep Blade sections in lowercase kebab IDs (for
|
|
example, `@section('order-summary')`).
|
|
|
|
## Testing Guidelines
|
|
|
|
Use PHPUnit via `php artisan test`; target deterministic tests with
|
|
clear Arrange/Act/Assert blocks. Feature tests should mirror top-level
|
|
route names (e.g., `OrdersTest.php`). Unit tests belong in
|
|
`tests/Unit/` and should stub external services. When adding
|
|
migrations or service integrations, include coverage that exercises
|
|
failure paths. For granular checks, `./vendor/bin/phpunit --filter
|
|
FooTest` is acceptable, but always run the full suite before pushing.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Commits in this repo mix Conventional Commit prefixes (`new:`, `fix:`,
|
|
`chg:`); `fix: prevent null totals`. Keep messages in the imperative
|
|
mood and reference ticket IDs when available.
|
|
|
|
Pull requests must describe scope, list schema or configuration
|
|
changes, and note any manual follow-up (cron, storage links,
|
|
queues).
|
|
|
|
Attach screenshots or terminal logs when touching UI or console
|
|
output, and ensure CI scripts (when available) pass.
|
|
|
|
## Environment & Security Notes
|
|
|
|
Copy `.env.example` to `.env` and run `php artisan key:generate`
|
|
before local work. Never commit `.env`, `storage/`, or database dumps
|
|
containing sensitive data. Use the Docker resources in `docker/` only
|
|
for reproducible environments; keep secrets in your host overrides,
|
|
not in version control.
|