OpenProject AI Coding Agent Instructions

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.

Repository Overview

OpenProject is a web-based, open-source project management software written in Ruby on Rails with PostgreSQL for data persistence.

Size: Large monorepo (~840MB, ~1M+ lines of code)
Backend: Ruby 3.4.7, Rails ~8.0.3
Frontend: Node.js 22.21.0, npm 10.1.0+, TypeScript
Database: PostgreSQL (required)
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.
Editions: Community, Enterprise (SSO, LDAP, SCIM), and BIM (construction industry, code in modules/bim/)

Critical Setup Requirements

ALWAYS verify versions before building:

Ruby: 3.4.7 (see .ruby-version)
Node: ^22.21.0 (see package.json engines)
Bundler: Latest 2.x

OpenProject supports two development setups: Local and Docker. Choose one based on your preference.

Local Development Setup

bundle install                    # Install Ruby gems
cd frontend && npm ci && cd ..   # Install Node packages
bundle exec rails db:migrate      # Setup database
bin/dev                          # Start all services (Rails, frontend, Good Job worker)
# Access at http://localhost:3000

Docker Development Setup

The Docker development environment uses configurations in docker/dev/ and the bin/compose wrapper script.

# Initial setup (first time only)
bin/compose setup                         # Installs backend and frontend dependencies

# Starting services
bin/compose start                         # Start backend and frontend in background
bin/compose run                           # Start frontend in background, backend in foreground (for debugging with pry)

# Running tests
bin/compose rspec spec/models/user_spec.rb   # Run specific tests in backend-test container

# Other operations
bin/compose reset                         # Remove all containers and volumes (requires setup again)
bin/compose <command>                     # Pass any docker-compose command directly

Important Docker Notes:

CRITICAL: config/database.yml must NOT exist when using Docker (rename or delete it)
Most developers use a local docker-compose.override.yml for custom port mappings and configurations
Copy docker-compose.override.example.yml to docker-compose.override.yml and customize as needed
Default ports: Backend at http://localhost:3000 (or 4200 for frontend dev server)
Services: backend, frontend, worker, db, db-test, backend-test, cache
Persisted volumes: pgdata, bundle, npm, tmp, opdata (data survives container restarts)
Docker build context: Uses Dockerfiles in docker/dev/backend/ and docker/dev/frontend/

Project Structure

Key Directories

app/ - Rails application code
- app/components/ - ViewComponent-based UI components (Ruby + ERB)
- app/contracts/ - Validation and authorization contracts
- app/controllers/ - Rails controllers
- app/models/ - ActiveRecord models
- app/services/ - Service objects (business logic)
- app/workers/ - Background job workers
config/ - Rails configuration, routes, locales
db/ - Database migrations and seeds
frontend/src/ - Frontend code
- frontend/src/app/ - Legacy Angular modules/components
- frontend/src/stimulus/ - Stimulus controllers
- frontend/src/turbo/ - Turbo integration
lib/ - Ruby libraries and extensions
lookbook/ - ViewComponent previews (https://qa.openproject-edge.com/lookbook/)
modules/ - OpenProject plugin modules
spec/ - RSpec test suite
- spec/features/ - System/feature tests (Capybara)
- spec/models/ - Model unit tests
- spec/requests/ - API/integration tests
- spec/services/ - Service tests

Configuration Files

.ruby-version - Ruby version
.rubocop.yml - Ruby linting rules
.erb_lint.yml - ERB template linting
frontend/eslint.config.mjs - JavaScript/TypeScript linting
Gemfile - Ruby dependencies
package.json / frontend/package.json - Node.js dependencies
lefthook.yml - Git hooks configuration

Building and Testing

Linting (Run Before Committing)

# Ruby
bundle exec rubocop                              # Check all files
bin/dirty-rubocop --uncommitted                  # Check only uncommitted changes

# JavaScript/TypeScript
cd frontend && npx eslint src/ && cd ..

# ERB Templates
erb_lint {files}

# Install Git Hooks (recommended)
bundle exec lefthook install

Running Tests

# Backend (RSpec) - prefer specific tests over running all
bundle exec rspec spec/models/user_spec.rb              # Single file
bundle exec rspec spec/models/user_spec.rb:42           # Single line
bundle exec rspec spec/features                         # Directory
bundle exec rake parallel:spec                          # Parallel execution

# Frontend (Jasmine/Karma)
cd frontend && npm test && cd ..

Debugging CI Failures

./script/github_pr_errors | xargs bundle exec rspec    # Run failed tests from CI
./script/bulk_run_rspec spec/path/to/flaky_spec.rb     # Run tests multiple times

Code Style Guidelines

Ruby

Follow Ruby community style guide
Use service objects for complex business logic (return ServiceResult)
Use contracts for validation and authorization
Keep controllers thin, models focused
Document with YARD
Write RSpec tests for all new features

JavaScript/TypeScript

New development: Use Hotwire (Turbo + Stimulus) with server-rendered HTML
Legacy code: Follow ESLint rules
Prefer TypeScript over JavaScript
Use Primer Design System via ViewComponent

Templates

Use ERB for server-rendered views
Use ViewComponents for reusable UI (with Lookbook previews)
Lint with erb_lint before committing

Database Migrations

Follow Rails migration conventions
Migrations are "squashed" between major releases (see docs/development/migrations/)

Translations

UI strings must use translation keys (never hard-coded)
Source translations in **/config/locales/en.yml can be modified directly
Other translations managed via Crowdin

Commit Messages

First line: < 72 characters, then blank line, then detailed description
Reference work packages when applicable
Merge strategy: "Merge pull request" (not squash), except single-commit PRs can use "Rebase and merge"

Important Commands Reference

Local Development Commands

# Setup
bin/setup              # Initial Rails setup
bin/setup_dev          # Full dev environment setup

# Database
bundle exec rails g migration MigrationName  # Generate a migration
bundle exec rails db:migrate                 # Run migrations
bundle exec rails db:rollback                # Rollback last migration
bundle exec rails db:seed                    # Seed sample data

# Development
bin/dev                                  # Start all services
bundle exec rails console                # Rails console
bundle exec rails routes                 # List routes

# Testing
bundle exec rspec                        # Run RSpec tests
bundle exec rails parallel:spec          # Parallel tests
cd frontend && npm test                  # Frontend tests

# Linting
bundle exec rubocop                      # Ruby linting
cd frontend && npx eslint src/           # JS/TS linting
erb_lint {files}                         # ERB linting

Docker Development Commands

# Setup and lifecycle
bin/compose setup                        # Setup Docker environment (first time)
bin/compose start                        # Start all services in background
bin/compose run                          # Start frontend in background, backend in foreground
bin/compose reset                        # Remove all containers and volumes
bin/compose stop                         # Stop all services
bin/compose down                         # Stop and remove containers

# Testing
bin/compose rspec spec/models/user_spec.rb    # Run specific tests
bin/compose exec backend bundle exec rspec    # Run tests directly in backend container

# Development
bin/compose exec backend bundle exec rails console   # Rails console
bin/compose logs backend                 # View backend logs
bin/compose logs -f backend              # Follow backend logs
bin/compose ps                           # List running containers

# Database
bin/compose exec backend bundle exec rails db:migrate      # Run migrations
bin/compose exec backend bundle exec rails db:seed         # Seed data

# Direct docker-compose commands
bin/compose up -d                        # Start services
bin/compose restart backend              # Restart backend service

Additional Documentation

docs/development/ - Development documentation
docs/development/running-tests/ - Testing guide
docs/development/code-review-guidelines/ - Code review standards
CONTRIBUTING.md - Contribution workflow
.github/copilot-instructions.md - Extended agent instructions with troubleshooting

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenProject AI Coding Agent Instructions

Repository Overview

Critical Setup Requirements

Local Development Setup

Docker Development Setup

Project Structure

Key Directories

Configuration Files

Building and Testing

Linting (Run Before Committing)

Running Tests

Debugging CI Failures

Code Style Guidelines

Ruby

JavaScript/TypeScript

Templates

Database Migrations

Translations

Commit Messages

Important Commands Reference

Local Development Commands

Docker Development Commands

Additional Documentation

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

OpenProject AI Coding Agent Instructions

Repository Overview

Critical Setup Requirements

Local Development Setup

Docker Development Setup

Project Structure

Key Directories

Configuration Files

Building and Testing

Linting (Run Before Committing)

Running Tests

Debugging CI Failures

Code Style Guidelines

Ruby

JavaScript/TypeScript

Templates

Database Migrations

Translations

Commit Messages

Important Commands Reference

Local Development Commands

Docker Development Commands

Additional Documentation