From 7d49707c4b9ebcf6dbcd478eda0f09b6e58d87b3 Mon Sep 17 00:00:00 2001 From: Dombi Attila <83396+dombesz@users.noreply.github.com> Date: Wed, 18 Mar 2026 14:56:43 +0200 Subject: [PATCH] Revert "Split the root Agent.md files into subdirectories." --- AGENTS.md | 184 ++++++++++++++++++++++++++++++++++++++----- app/AGENTS.md | 31 -------- app/CLAUDE.md | 1 - config/AGENTS.md | 14 ---- config/CLAUDE.md | 1 - db/AGENTS.md | 30 ------- db/CLAUDE.md | 1 - docker/dev/AGENTS.md | 61 -------------- docker/dev/CLAUDE.md | 1 - frontend/AGENTS.md | 46 ----------- frontend/CLAUDE.md | 1 - spec/AGENTS.md | 32 -------- spec/CLAUDE.md | 1 - 13 files changed, 166 insertions(+), 238 deletions(-) delete mode 100644 app/AGENTS.md delete mode 120000 app/CLAUDE.md delete mode 100644 config/AGENTS.md delete mode 120000 config/CLAUDE.md delete mode 100644 db/AGENTS.md delete mode 120000 db/CLAUDE.md delete mode 100644 docker/dev/AGENTS.md delete mode 120000 docker/dev/CLAUDE.md delete mode 100644 frontend/AGENTS.md delete mode 120000 frontend/CLAUDE.md delete mode 100644 spec/AGENTS.md delete mode 120000 spec/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 7ec29b0adc3..dac00fe3410 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,8 @@ - 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 ```bash @@ -32,24 +34,59 @@ bin/dev # Start all services (Rails, frontend, Good Job ### Docker Development Setup -See [`docker/dev/AGENTS.md`](docker/dev/AGENTS.md) for full Docker setup and commands. +The Docker development environment uses configurations in `docker/dev/` and the `bin/compose` wrapper script. + +```bash +# 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 # 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 -- `config/` — Rails configuration, routes, locales -- `db/` — Database migrations and seeds -- `docker/dev/` — Docker development environment -- `frontend/` — TypeScript/Angular/Stimulus frontend -- `lib/` — Ruby libraries and extensions -- `lookbook/` — ViewComponent previews () -- `modules/` — OpenProject plugin modules -- `spec/` — RSpec test suite +- `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 @@ -58,6 +95,8 @@ See [`docker/dev/AGENTS.md`](docker/dev/AGENTS.md) for full Docker setup and com - `package.json` / `frontend/package.json` - Node.js dependencies - `lefthook.yml` - Git hooks configuration +## Building and Testing + ### Linting (Run Before Committing) ```bash @@ -75,16 +114,125 @@ erb_lint {files} bundle exec lefthook install ``` -## Commit Messages +### Running Tests +```bash +# 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 +```bash +./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](https://github.com/bbatsov/ruby-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](https://yardoc.org/) +- 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](https://primer.style/product/) 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 + +```bash +# 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 + +```bash +# 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 +- `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 diff --git a/app/AGENTS.md b/app/AGENTS.md deleted file mode 100644 index 6da76af89b3..00000000000 --- a/app/AGENTS.md +++ /dev/null @@ -1,31 +0,0 @@ -# App - -## Directory Structure - -- `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 - -## Code Style - -### Ruby - -- Follow [Ruby community style guide](https://github.com/bbatsov/ruby-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](https://yardoc.org/) -- Write RSpec tests for all new features - -### Templates - -- Use ERB for server-rendered views -- Use ViewComponents for reusable UI (with Lookbook previews) -- Lint with erb_lint before committing - -## Translations - -- UI strings must use translation keys (never hard-coded) diff --git a/app/CLAUDE.md b/app/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/app/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/config/AGENTS.md b/config/AGENTS.md deleted file mode 100644 index c2f55641e23..00000000000 --- a/config/AGENTS.md +++ /dev/null @@ -1,14 +0,0 @@ -# Config - -## 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 - -```bash -bundle exec i18n-tasks missing # Show missing translation keys -bundle exec i18n-tasks unused # Show unused translation keys -bundle exec i18n-tasks normalize # Fix/normalize translation files -bundle exec i18n-tasks check-consistent-interpolations # Check interpolation consistency -``` diff --git a/config/CLAUDE.md b/config/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/config/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/db/AGENTS.md b/db/AGENTS.md deleted file mode 100644 index a80ff4f767b..00000000000 --- a/db/AGENTS.md +++ /dev/null @@ -1,30 +0,0 @@ -# Database - -## Code Style - -### Database Migrations - -- Follow Rails migration conventions -- Migrations are "squashed" between major releases (see `docs/development/migrations/`) - -## Commands - -### Local - -```bash -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 -``` - -### Docker - -```bash -bin/compose exec backend bundle exec rails db:migrate # Run migrations -bin/compose exec backend bundle exec rails db:seed # Seed data -``` - -## Important Note - -**CRITICAL**: `config/database.yml` must NOT exist when using Docker (rename or delete it) diff --git a/db/CLAUDE.md b/db/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/db/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/docker/dev/AGENTS.md b/docker/dev/AGENTS.md deleted file mode 100644 index f7492804b5a..00000000000 --- a/docker/dev/AGENTS.md +++ /dev/null @@ -1,61 +0,0 @@ -# Docker Development - -The Docker development environment uses configurations in `docker/dev/` and the `bin/compose` wrapper script. - -## Setup - -```bash -# 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 # Pass any docker-compose command directly -``` - -## Important 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/` - -## Commands Reference - -```bash -# 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 -``` diff --git a/docker/dev/CLAUDE.md b/docker/dev/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/docker/dev/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md deleted file mode 100644 index 892d0242019..00000000000 --- a/frontend/AGENTS.md +++ /dev/null @@ -1,46 +0,0 @@ -# Frontend - -## Directory Structure - -- `./src/` - Frontend code - - `./src/app/` - Legacy Angular modules/components - - `./src/stimulus/` - Stimulus controllers - - `./src/turbo/` - Turbo integration - -## Configuration Files - -- `eslint.config.mjs` - JavaScript/TypeScript linting -- `../package.json` / `./frontend/package.json` - Node.js dependencies - -## Version Requirements - -- Node: `^22.21.0` (see `package.json` engines) - -## Setup - -```bash -npm ci && cd .. # Install Node packages -``` - -## Code Style - -### 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](https://primer.style/product/) via ViewComponent - -## Linting - -```bash -# JavaScript/TypeScript -npx eslint src/ && cd .. -``` - -## Testing - -```bash -# Frontend (Jasmine/Karma) -npm test && cd .. -``` diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/frontend/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/spec/AGENTS.md b/spec/AGENTS.md deleted file mode 100644 index f5fd6ce1e62..00000000000 --- a/spec/AGENTS.md +++ /dev/null @@ -1,32 +0,0 @@ -# Spec - -## Directory Structure - -- `spec/features/` - System/feature tests (Capybara) -- `spec/models/` - Model unit tests -- `spec/requests/` - API/integration tests -- `spec/services/` - Service tests - -## Running Tests - -```bash -# 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 -RAILS_ENV=test ./bin/rails parallel:spec # Parallel execution -``` - -### Docker - -```bash -bin/compose rspec spec/models/user_spec.rb # Run specific tests in backend-test container -bin/compose exec backend bundle exec rspec # Run tests directly in backend container -``` - -## Debugging CI Failures - -```bash -./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 -``` diff --git a/spec/CLAUDE.md b/spec/CLAUDE.md deleted file mode 120000 index 47dc3e3d863..00000000000 --- a/spec/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file