Copilot instructions

1# OpenProject Coding Agent Instructions
2 
3See [AGENTS.md](../AGENTS.md) for all agent instructions.
4 
5## Additional Context for GitHub Copilot
6 
7### Common Issues and Workarounds
8 
9#### Database Configuration
10- **Issue**: Docker fails with "database.yml exists"
11- **Fix**: Delete or rename `config/database.yml` when using Docker
12 
13#### Memory Issues in Docker
14- **Issue**: Frontend container exits with status 137
15- **Fix**: Increase Docker memory limit to at least 4GB
16 
17#### Test Failures on CI but Passing Locally
18- Run with `CI=true` environment variable (eager loads app)
19- Check for `OPENPROJECT_*` environment variables
20- Match the random seed: `bundle exec rspec --seed 18352`
21- Use `--bisect` to find order-dependent failures
22- View browser tests with `OPENPROJECT_TESTING_NO_HEADLESS=1`
23 
24#### Frontend Build Issues
25- **Issue**: "jQuery not defined", frontend asset errors, or blank page
26- **Fix**: Run `bin/setup_dev` to rebuild frontend completely
27 
28#### Parallel Test Failures
29- Tests run in parallel on CI with different random seeds per group
30- Check `tmp/parallel_runtime.log` for execution times
31- **Flaky specs**: Some tests may fail randomly; see [`docs/development/testing/handling-flaky-tests/README.md`](../docs/development/testing/handling-flaky-tests/README.md) for the full playbook, including the Turbo-aware waiting helpers and a pattern→fix table for feature specs
32  - Use `script/bulk_run_rspec` to run tests multiple times to identify flaky behavior
33 
34### Extended Details
35 
36#### Service Objects and Result Modeling
37- Return results using the `ServiceResult` class (well-documented in codebase)
38- Some services use monads via [dry-monads](https://github.com/dry-rb/dry-monads) for result modeling
39 
40#### Testing with Capybara
41- Feature specs use Capybara (with Cuprite and Selenium WebDriver)
42- Feature specs can use A11y selectors ([capybara_accessible_selectors](https://github.com/citizensadvice/capybara_accessible_selectors)), test IDs, or page objects (in `spec/support/pages/`)
43 
44#### Database Migrations
45- OpenProject implements migration "squashing" between major releases
46- See `docs/development/migrations/` for details on the squashing process
47- Migrations are consolidated to manage database changes across major versions
48- OpenProject does not currently aim for zero downtime migrations
49 
50#### Design System Components
51- [primer_view_components](https://github.com/opf/primer_view_components) - OpenProject's fork of Primer Rails/ViewComponent
52- [openproject-octicons](https://github.com/opf/openproject-octicons) - OpenProject's fork of Primer Octicons
53- [commonmark-ckeditor-build](https://github.com/opf/commonmark-ckeditor-build) - Custom CKEditor build with CommonMark Markdown support
54 
55#### Enterprise and BIM Editions
56- **Enterprise Edition**: Includes additional features like Single sign-on (OIDC & SAML), LDAP, Nextcloud integration, SCIM API, and more (requires token for development)
57- **BIM Edition**: Tailored for construction industry needs. Code in `modules/bim/`, docs in `docs/bim-guide/`. Existing instances can be switched to BIM edition.
58 
59#### GitHub Actions CI/CD
60- **test-core.yml** - Main test suite (units + features, ~40 min, runs on all PRs)
61- **rubocop-core.yml** - Ruby linting (runs on all PRs with Ruby changes)
62- **eslint-core.yml** - JS/TS linting (runs on all PRs with JS/TS changes)
63- **test-frontend-unit.yml** - Frontend unit tests
64- **brakeman-scan-core.yml** - Security scanning
65- **codeql-scan-core.yml** - Code quality/security analysis
66- **Skip CI**: Add `[ci skip]` to commit message to skip CI (use sparingly)
67 
68#### Performance Considerations
69- Main test suite: 40 minutes timeout
70- Full Docker build: ~10-15 minutes (first time)
71- Bundle install: ~2-5 minutes
72- npm install: ~3-7 minutes
73 
74### Additional Commands
75 
76```bash
77# Database
78bundle exec rake db:migrate:status       # Check migration status
79 
80# Frontend
81bundle exec rails openproject:plugins:register_frontend assets:export_locales
82 
83# Docker
84bin/compose run                          # Run with backend in foreground
85docker compose run --rm backend-test "bundle exec rspec spec/features/work_package_show_spec.rb"
86```
87 
88For detailed documentation, consult:
89- `docs/development/` - Development documentation
90- `docs/development/running-tests/` - Testing guide
91- `docs/development/code-review-guidelines/` - Code review standards
92- `CONTRIBUTING.md` - Contribution workflow
93