Skip to content

Commit 443cb57

Browse files
Copilotjbtronics
Copilot
and
jbtronics
authored
Add Copilot instructions for repository (#1135)
* Initial plan * Add comprehensive Copilot instructions for Part-DB Co-authored-by: jbtronics <[email protected]> * Fix Symfony version and fixtures command in Copilot instructions Co-authored-by: jbtronics <[email protected]> * Remove PHP code style check instructions Removed code style check instructions for PHP. --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: jbtronics <[email protected]> Co-authored-by: Jan Böhmer <[email protected]>
1 parent 9dc17ad commit 443cb57

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Copilot Instructions for Part-DB
2+
3+
Part-DB is an Open-Source inventory management system for electronic components built with Symfony 7.4 and modern web technologies.
4+
5+
## Technology Stack
6+
7+
- **Backend**: PHP 8.2+, Symfony 7.4, Doctrine ORM
8+
- **Frontend**: Bootstrap 5, Hotwire Stimulus/Turbo, TypeScript, Webpack Encore
9+
- **Database**: MySQL 5.7+/MariaDB 10.4+/PostgreSQL 10+/SQLite
10+
- **Testing**: PHPUnit with DAMA Doctrine Test Bundle
11+
- **Code Quality**: Easy Coding Standard (ECS), PHPStan (level 5)
12+
13+
## Project Structure
14+
15+
- `src/`: PHP application code organized by purpose (Controller, Entity, Service, Form, etc.)
16+
- `assets/`: Frontend TypeScript/JavaScript and CSS files
17+
- `templates/`: Twig templates for views
18+
- `tests/`: PHPUnit tests mirroring the `src/` structure
19+
- `config/`: Symfony configuration files
20+
- `public/`: Web-accessible files
21+
- `translations/`: Translation files for multi-language support
22+
23+
## Coding Standards
24+
25+
### PHP Code
26+
27+
- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) and [Symfony coding standards](https://symfony.com/doc/current/contributing/code/standards.html)
28+
- Use type hints for all parameters and return types
29+
- Always declare strict types: `declare(strict_types=1);` at the top of PHP files
30+
- Use PHPDoc blocks for complex logic or when type information is needed
31+
32+
### TypeScript/JavaScript
33+
34+
- Use TypeScript for new frontend code
35+
- Follow existing Stimulus controller patterns in `assets/controllers/`
36+
- Use Bootstrap 5 components and utilities
37+
- Leverage Hotwire Turbo for dynamic page updates
38+
39+
### Naming Conventions
40+
41+
- Entities: Use descriptive names that reflect database models (e.g., `Part`, `StorageLocation`)
42+
- Controllers: Suffix with `Controller` (e.g., `PartController`)
43+
- Services: Descriptive names reflecting their purpose (e.g., `PartService`, `LabelGenerator`)
44+
- Tests: Match the class being tested with `Test` suffix (e.g., `PartTest`, `PartControllerTest`)
45+
46+
## Development Workflow
47+
48+
### Dependencies
49+
50+
- Install PHP dependencies: `composer install`
51+
- Install JS dependencies: `yarn install`
52+
- Build frontend assets: `yarn build` (production) or `yarn watch` (development)
53+
54+
### Database
55+
56+
- Create database: `php bin/console doctrine:database:create --env=dev`
57+
- Run migrations: `php bin/console doctrine:migrations:migrate --env=dev`
58+
- Load fixtures: `php bin/console partdb:fixtures:load -n --env=dev`
59+
60+
Or use Makefile shortcuts:
61+
- `make dev-setup`: Complete development environment setup
62+
- `make dev-reset`: Reset development environment (cache clear + migrate)
63+
64+
### Testing
65+
66+
- Set up test environment: `make test-setup`
67+
- Run all tests: `php bin/phpunit`
68+
- Run specific test: `php bin/phpunit tests/Path/To/SpecificTest.php`
69+
- Run tests with coverage: `php bin/phpunit --coverage-html var/coverage`
70+
- Test environment uses SQLite by default for speed
71+
72+
### Static Analysis
73+
74+
- Run PHPStan: `composer phpstan` or `COMPOSER_MEMORY_LIMIT=-1 php -d memory_limit=1G vendor/bin/phpstan analyse src --level 5`
75+
- PHPStan configuration is in `phpstan.dist.neon`
76+
77+
### Running the Application
78+
79+
- Development server: `symfony serve` (requires Symfony CLI)
80+
- Or configure Apache/nginx to serve from `public/` directory
81+
- Set `APP_ENV=dev` in `.env.local` for development mode
82+
83+
## Best Practices
84+
85+
### Security
86+
87+
- Always sanitize user input
88+
- Use Symfony's security component for authentication/authorization
89+
- Check permissions using the permission system before allowing actions
90+
- Never expose sensitive data in logs or error messages
91+
- Use parameterized queries (Doctrine handles this automatically)
92+
93+
### Performance
94+
95+
- Use Doctrine query builder for complex queries instead of DQL when possible
96+
- Lazy load relationships to avoid N+1 queries
97+
- Cache results when appropriate using Symfony's cache component
98+
- Use pagination for large result sets (DataTables integration available)
99+
100+
### Database
101+
102+
- Always create migrations for schema changes: `php bin/console make:migration`
103+
- Review migration files before running them
104+
- Use Doctrine annotations or attributes for entity mapping
105+
- Follow existing entity patterns for relationships and lifecycle callbacks
106+
107+
### Frontend
108+
109+
- Use Stimulus controllers for interactive components
110+
- Leverage Turbo for dynamic page updates without full page reloads
111+
- Use Bootstrap 5 classes for styling
112+
- Keep JavaScript modular and organized in controllers
113+
- Use the translation system for user-facing strings
114+
115+
### Translations
116+
117+
- Use translation keys, not hardcoded strings: `{{ 'part.info.title'|trans }}`
118+
- Add new translation keys to `translations/` files
119+
- Primary language is English (en)
120+
- Translations are managed via Crowdin, but can be edited locally if needed
121+
122+
### Testing
123+
124+
- Write unit tests for services and helpers
125+
- Write functional tests for controllers
126+
- Use fixtures for test data
127+
- Tests should be isolated and not depend on execution order
128+
- Mock external dependencies when appropriate
129+
- Follow existing test patterns in the repository
130+
131+
## Common Patterns
132+
133+
### Creating an Entity
134+
135+
1. Create entity class in `src/Entity/` with Doctrine attributes
136+
2. Generate migration: `php bin/console make:migration`
137+
3. Review and run migration: `php bin/console doctrine:migrations:migrate`
138+
4. Create repository if needed in `src/Repository/`
139+
5. Add fixtures in `src/DataFixtures/` for testing
140+
141+
### Adding a Form
142+
143+
1. Create form type in `src/Form/`
144+
2. Extend `AbstractType` and implement `buildForm()` and `configureOptions()`
145+
3. Use in controller and render in Twig template
146+
4. Follow existing form patterns for consistency
147+
148+
### Creating a Controller Action
149+
150+
1. Add method to appropriate controller in `src/Controller/`
151+
2. Use route attributes for routing
152+
3. Check permissions using security voters
153+
4. Return Response or render Twig template
154+
5. Add corresponding template in `templates/`
155+
156+
### Adding a Service
157+
158+
1. Create service class in `src/Services/`
159+
2. Use dependency injection via constructor
160+
3. Tag service in `config/services.yaml` if needed
161+
4. Services are autowired by default
162+
163+
## Important Notes
164+
165+
- Part-DB uses fine-grained permissions - always check user permissions before actions
166+
- Multi-language support is critical - use translation keys everywhere
167+
- The application supports multiple database backends - write portable code
168+
- Responsive design is important - test on mobile/tablet viewports
169+
- Event system is used for logging changes - emit events when appropriate
170+
- API Platform is integrated for REST API endpoints
171+
172+
## Multi-tenancy Considerations
173+
174+
- Part-DB is designed as a single-tenant application with multiple users
175+
- User groups have different permission levels
176+
- Always scope queries to respect user permissions
177+
- Use the security context to get current user information
178+
179+
## Resources
180+
181+
- [Documentation](https://docs.part-db.de/)
182+
- [Contributing Guide](CONTRIBUTING.md)
183+
- [Symfony Documentation](https://symfony.com/doc/current/index.html)
184+
- [Doctrine Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/current/)
185+
- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.1/)
186+
- [Hotwire Documentation](https://hotwired.dev/)

0 commit comments

Comments
 (0)