From 443cb57ce8fda5deaa8e559af10050a3f14379b9 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Dec 2025 22:57:48 +0100 Subject: [PATCH] Add Copilot instructions for repository (#1135) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * Add comprehensive Copilot instructions for Part-DB Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com> * Fix Symfony version and fixtures command in Copilot instructions Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com> * Remove PHP code style check instructions Removed code style check instructions for PHP. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com> Co-authored-by: Jan Böhmer --- .github/copilot-instructions.md | 186 ++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..637a66b5 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,186 @@ +# Copilot Instructions for Part-DB + +Part-DB is an Open-Source inventory management system for electronic components built with Symfony 7.4 and modern web technologies. + +## Technology Stack + +- **Backend**: PHP 8.2+, Symfony 7.4, Doctrine ORM +- **Frontend**: Bootstrap 5, Hotwire Stimulus/Turbo, TypeScript, Webpack Encore +- **Database**: MySQL 5.7+/MariaDB 10.4+/PostgreSQL 10+/SQLite +- **Testing**: PHPUnit with DAMA Doctrine Test Bundle +- **Code Quality**: Easy Coding Standard (ECS), PHPStan (level 5) + +## Project Structure + +- `src/`: PHP application code organized by purpose (Controller, Entity, Service, Form, etc.) +- `assets/`: Frontend TypeScript/JavaScript and CSS files +- `templates/`: Twig templates for views +- `tests/`: PHPUnit tests mirroring the `src/` structure +- `config/`: Symfony configuration files +- `public/`: Web-accessible files +- `translations/`: Translation files for multi-language support + +## Coding Standards + +### PHP Code + +- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) and [Symfony coding standards](https://symfony.com/doc/current/contributing/code/standards.html) +- Use type hints for all parameters and return types +- Always declare strict types: `declare(strict_types=1);` at the top of PHP files +- Use PHPDoc blocks for complex logic or when type information is needed + +### TypeScript/JavaScript + +- Use TypeScript for new frontend code +- Follow existing Stimulus controller patterns in `assets/controllers/` +- Use Bootstrap 5 components and utilities +- Leverage Hotwire Turbo for dynamic page updates + +### Naming Conventions + +- Entities: Use descriptive names that reflect database models (e.g., `Part`, `StorageLocation`) +- Controllers: Suffix with `Controller` (e.g., `PartController`) +- Services: Descriptive names reflecting their purpose (e.g., `PartService`, `LabelGenerator`) +- Tests: Match the class being tested with `Test` suffix (e.g., `PartTest`, `PartControllerTest`) + +## Development Workflow + +### Dependencies + +- Install PHP dependencies: `composer install` +- Install JS dependencies: `yarn install` +- Build frontend assets: `yarn build` (production) or `yarn watch` (development) + +### Database + +- Create database: `php bin/console doctrine:database:create --env=dev` +- Run migrations: `php bin/console doctrine:migrations:migrate --env=dev` +- Load fixtures: `php bin/console partdb:fixtures:load -n --env=dev` + +Or use Makefile shortcuts: +- `make dev-setup`: Complete development environment setup +- `make dev-reset`: Reset development environment (cache clear + migrate) + +### Testing + +- Set up test environment: `make test-setup` +- Run all tests: `php bin/phpunit` +- Run specific test: `php bin/phpunit tests/Path/To/SpecificTest.php` +- Run tests with coverage: `php bin/phpunit --coverage-html var/coverage` +- Test environment uses SQLite by default for speed + +### Static Analysis + +- Run PHPStan: `composer phpstan` or `COMPOSER_MEMORY_LIMIT=-1 php -d memory_limit=1G vendor/bin/phpstan analyse src --level 5` +- PHPStan configuration is in `phpstan.dist.neon` + +### Running the Application + +- Development server: `symfony serve` (requires Symfony CLI) +- Or configure Apache/nginx to serve from `public/` directory +- Set `APP_ENV=dev` in `.env.local` for development mode + +## Best Practices + +### Security + +- Always sanitize user input +- Use Symfony's security component for authentication/authorization +- Check permissions using the permission system before allowing actions +- Never expose sensitive data in logs or error messages +- Use parameterized queries (Doctrine handles this automatically) + +### Performance + +- Use Doctrine query builder for complex queries instead of DQL when possible +- Lazy load relationships to avoid N+1 queries +- Cache results when appropriate using Symfony's cache component +- Use pagination for large result sets (DataTables integration available) + +### Database + +- Always create migrations for schema changes: `php bin/console make:migration` +- Review migration files before running them +- Use Doctrine annotations or attributes for entity mapping +- Follow existing entity patterns for relationships and lifecycle callbacks + +### Frontend + +- Use Stimulus controllers for interactive components +- Leverage Turbo for dynamic page updates without full page reloads +- Use Bootstrap 5 classes for styling +- Keep JavaScript modular and organized in controllers +- Use the translation system for user-facing strings + +### Translations + +- Use translation keys, not hardcoded strings: `{{ 'part.info.title'|trans }}` +- Add new translation keys to `translations/` files +- Primary language is English (en) +- Translations are managed via Crowdin, but can be edited locally if needed + +### Testing + +- Write unit tests for services and helpers +- Write functional tests for controllers +- Use fixtures for test data +- Tests should be isolated and not depend on execution order +- Mock external dependencies when appropriate +- Follow existing test patterns in the repository + +## Common Patterns + +### Creating an Entity + +1. Create entity class in `src/Entity/` with Doctrine attributes +2. Generate migration: `php bin/console make:migration` +3. Review and run migration: `php bin/console doctrine:migrations:migrate` +4. Create repository if needed in `src/Repository/` +5. Add fixtures in `src/DataFixtures/` for testing + +### Adding a Form + +1. Create form type in `src/Form/` +2. Extend `AbstractType` and implement `buildForm()` and `configureOptions()` +3. Use in controller and render in Twig template +4. Follow existing form patterns for consistency + +### Creating a Controller Action + +1. Add method to appropriate controller in `src/Controller/` +2. Use route attributes for routing +3. Check permissions using security voters +4. Return Response or render Twig template +5. Add corresponding template in `templates/` + +### Adding a Service + +1. Create service class in `src/Services/` +2. Use dependency injection via constructor +3. Tag service in `config/services.yaml` if needed +4. Services are autowired by default + +## Important Notes + +- Part-DB uses fine-grained permissions - always check user permissions before actions +- Multi-language support is critical - use translation keys everywhere +- The application supports multiple database backends - write portable code +- Responsive design is important - test on mobile/tablet viewports +- Event system is used for logging changes - emit events when appropriate +- API Platform is integrated for REST API endpoints + +## Multi-tenancy Considerations + +- Part-DB is designed as a single-tenant application with multiple users +- User groups have different permission levels +- Always scope queries to respect user permissions +- Use the security context to get current user information + +## Resources + +- [Documentation](https://docs.part-db.de/) +- [Contributing Guide](CONTRIBUTING.md) +- [Symfony Documentation](https://symfony.com/doc/current/index.html) +- [Doctrine Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/current/) +- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.1/) +- [Hotwire Documentation](https://hotwired.dev/)