AGENTS.md

1# OpenProject AI Coding Agent Instructions
2 
3> **Note for developers**: You can create `AGENTS.local.md` (or `CLAUDE.local.md`) in this directory to add your own custom instructions or preferences for AI coding agents. These files are git-ignored and will not be committed to the repository.
4 
5## Repository Overview
6 
7**OpenProject** is a web-based, open-source project management software written in Ruby on Rails with PostgreSQL for data persistence.
8 
9- **Size**: Large monorepo (~840MB, ~1M+ lines of code)
10- **Backend**: Ruby 3.4.7, Rails ~8.0.3
11- **Frontend**: Node.js 24.x (>= 24.15.0), npm 11.x, TypeScript
12- **Database**: PostgreSQL (required)
13- **Architecture**: Server-rendered HTML with Hotwire (Turbo + Stimulus). Legacy Angular components exist and are being migrated to custom elements. Uses GitHub's Primer Design System via ViewComponent.
14- **Editions**: Community, Enterprise (SSO, LDAP, SCIM), and BIM (construction industry, code in `modules/bim/`)
15 
16## Critical Setup Requirements
17 
18**ALWAYS verify versions before building:**
19- Ruby: `3.4.7` (see `.ruby-version`)
20- Node: `^24.15.0` (see `package.json` engines)
21- Bundler: Latest 2.x
22 
23### Local Development Setup
24 
25```bash
26bundle install                    # Install Ruby gems
27cd frontend && npm ci && cd ..   # Install Node packages
28bundle exec rails db:migrate      # Setup database
29bin/dev                          # Start all services (Rails, frontend, Good Job worker)
30# Access at http://localhost:3000
31```
32 
33### Docker Development Setup
34 
35See [`docker/dev/AGENTS.md`](docker/dev/AGENTS.md) for full Docker setup and commands.
36 
37## Project Structure
38 
39### Key Directories
40 
41- `app/` — Rails application code
42- `config/` — Rails configuration, routes, locales
43- `db/` — Database migrations and seeds
44- `docker/dev/` — Docker development environment
45- `frontend/` — TypeScript/Angular/Stimulus frontend
46- `lib/` — Ruby libraries and extensions
47- `lookbook/` — ViewComponent previews (<https://qa.openproject-edge.com/lookbook/>)
48- `modules/` — OpenProject plugin modules
49- `spec/` — RSpec test suite
50 
51### Configuration Files
52 
53- `.ruby-version` - Ruby version
54- `.rubocop.yml` - Ruby linting rules
55- `.erb_lint.yml` - ERB template linting
56- `frontend/eslint.config.mjs` - JavaScript/TypeScript linting
57- `Gemfile` - Ruby dependencies
58- `package.json` / `frontend/package.json` - Node.js dependencies
59- `lefthook.yml` - Git hooks configuration
60 
61### Linting (Run Before Committing)
62 
63```bash
64# Ruby
65bundle exec rubocop                              # Check all files
66bin/dirty-rubocop --uncommitted                  # Check only uncommitted changes
67 
68# JavaScript/TypeScript
69cd frontend && npx eslint src/ && cd ..
70 
71# ERB Templates
72erb_lint {files}
73 
74# Install Git Hooks (recommended)
75bundle exec lefthook install
76```
77 
78### JavaScript and TypeScript Copyright Headers
79 
80All first-party JavaScript and TypeScript files must use the canonical compact
81line-comment copyright header generated from `COPYRIGHT_short`:
82 
83```typescript
84//-- copyright
85// OpenProject is an open source project management software.
86// ...
87//++
88 
89```
90 
91Use `//-- copyright` and `//++` exactly as shown. Prefix non-empty body lines
92with `// `, prefix empty body lines with `//`, and leave one blank line between
93the header and the source code. Do not compose or reformat the header manually.
94 
95Run `rake copyright:update_typescript` to add or repair headers in `.ts` and
96`.tsx` files. Run `rake copyright:update_js` for `.js`, `.mjs`, and `.cjs`
97files. Both commands accept an optional path argument.
98 
99## Commit Messages
100- First line: < 72 characters, then blank line, then detailed description
101- Reference work packages when applicable
102- Merge strategy: "Merge pull request" (not squash), except single-commit PRs can use "Rebase and merge"
103 
104## Additional Documentation
105 
106- `docs/development/` — Development documentation
107- `docs/development/running-tests/` — Testing guide
108- `docs/development/code-review-guidelines/` — Code review standards
109- `CONTRIBUTING.md` — Contribution workflow
110- `.github/copilot-instructions.md` — Extended agent instructions with troubleshooting
111