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.

2.8 KiB Raw Blame History