| # AI Agent Project Profile: gerrit | |
| ## Project Overview | |
| Gerrit is a web-based code review system for Git. Backend is Java 21, frontend is TypeScript/Lit components, built with Bazel. | |
| The bazel version to be used can be read from the `.bazelversion` file. | |
| ## Sub-projects | |
| - **`polygerrit-ui`**: The frontend web application. See `polygerrit-ui/AGENTS.md` for details on the frontend development environment. | |
| ## Build tool selection | |
| If `bazelisk` is installed, use `bazelisk` instead of `bazel` for all build | |
| commands. | |
| ## Build Commands | |
| ```bash | |
| # Development WAR (output: bazel-bin/gerrit.war) | |
| bazel build gerrit | |
| # Release WAR with UI, core plugins, docs (output: bazel-bin/release.war) | |
| bazel build release | |
| # Build specific plugin | |
| bazel build plugins/<name> | |
| ``` | |
| ## Running Tests | |
| ### Java Tests | |
| ```bash | |
| # All tests | |
| bazel test --build_tests_only //... | |
| # Specific test target | |
| bazel test //javatests/com/google/gerrit/acceptance/rest/account:rest_account | |
| # Single test method | |
| bazel test --test_output=streamed \ | |
| --test_filter=com.google.gerrit.acceptance.api.change.ChangeIT.getAmbiguous \ | |
| //javatests/com/google/gerrit/acceptance/api/change:ChangeIT | |
| # Tests by tag (api, git, rest, server, ssh, notedb, edit, pgm, annotation) | |
| bazel test --test_tag_filters=api,git //... | |
| # Exclude flaky tests | |
| bazel test --test_tag_filters=-flaky //... | |
| # Force re-run (ignore cache) | |
| bazel test --cache_test_results=NO //... | |
| # Debug tests (attach debugger to port 5005) | |
| bazel test --java_debug //javatests/... | |
| ``` | |
| ## Linting & Formatting | |
| ```bash | |
| # Java - Google Java Format (required) | |
| ./tools/gjf.sh setup # First time setup | |
| ./tools/gjf.sh run # Format changed files | |
| npm run gjf # Alternative | |
| ``` | |
| ## Local Development | |
| ```bash | |
| # Set Java path (Java 21) | |
| # Example for macOS ARM64 - check $(bazel info output_base)/external/ for your platform's directory | |
| export JAVA_HOME=$(bazel info output_base)/external/rules_java~~toolchains~remotejdk21_macos_aarch64 | |
| export GERRIT_SITE=~/gerrit_testsite | |
| # Initialize test site (first time only) | |
| $JAVA_HOME/bin/java -jar bazel-bin/gerrit.war init --batch --dev -d $GERRIT_SITE | |
| # Run daemon (localhost:8080) | |
| $JAVA_HOME/bin/java \ | |
| -DsourceRoot=$(bazel info workspace) \ | |
| -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE --console-log | |
| # Run daemon with dev frontend (use frontend from localhost:8081) | |
| $JAVA_HOME/bin/java \ | |
| -DsourceRoot=$(bazel info workspace) \ | |
| -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE --console-log --dev-cdn http://localhost:8081 | |
| ``` | |
| ## Code Architecture | |
| ### Backend (java/com/google/gerrit/) | |
| - **server/**: Core server logic, change handling, review workflows | |
| - **httpd/**: REST API endpoints (servlet-based) | |
| - **git/**: JGit wrapper for repository operations | |
| - **index/**: Search backends (Lucene) | |
| - **entities/**: Core domain models (Change, PatchSet, Account) | |
| - **extensions/**: Plugin extension APIs | |
| - **pgm/**: CLI programs and commands | |
| - **acceptance/**: Test acceptance framework | |
| ### Plugins (plugins/) | |
| Core plugins as Git submodules: replication, hooks, delete-project, gitiles, webhooks, etc. | |
| Plugins extend via extension APIs in java/com/google/gerrit/extensions/. | |
| ## Code Style | |
| - Java: Google Java Style Guide, use `./tools/gjf.sh run` before committing | |
| - Commit messages: max 72 chars/line, present tense, include Change-Id (added by git hook) | |
| - **Release-Notes footer required**: Every commit must have `Release-Notes:` footer. Use `Release-Notes: skip` for small fixes/refactorings, or add a summary for notable changes | |
| - Optional Google-Bug-Id footer: Commits might have a `Google-Bug-Id: b/<number>` footer. If your context provides a bug number, use it. | |
| - **Copyright headers**: All new Java files must include the Apache 2.0 license header with the current year (e.g., `// Copyright (C) 2026 The Android Open Source Project`) | |
| ## Key Patterns | |
| - Dependency injection via Guice | |
| - REST endpoints return Java objects serialized to JSON | |
| - Changes stored in NoteDb (Git-based storage) | |
| - Event-driven architecture for plugins |