# https://github.com/reviewboard/ReviewBot Project Manual

Generated at: 2026-06-20 05:37:11 UTC

## Table of Contents

- [ReviewBot Overview & System Architecture](#page-1)
- [Supported Code Checking Tools & Configuration](#page-2)
- [Deployment & Infrastructure](#page-3)
- [Development, Extensibility & Operations](#page-4)

<a id='page-1'></a>

## ReviewBot Overview & System Architecture

### Related Pages

Related topics: [Supported Code Checking Tools & Configuration](#page-2), [Deployment & Infrastructure](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst)
- [bot/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/bot/README.rst)
- [extension/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/extension/README.rst)
- [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py)
- [bot/reviewbot/tools/base/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/__init__.py)
- [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py)
- [bot/reviewbot/repositories.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/repositories.py)
- [bot/reviewbot/tools/clang.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/clang.py)
- [bot/reviewbot/tools/jshint.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/jshint.py)
- [bot/reviewbot/tools/cargotool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/cargotool.py)
- [bot/reviewbot/tools/gotool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/gotool.py)
- [bot/reviewbot/tools/rubocop.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/rubocop.py)
- [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py)
- [bot/reviewbot/tools/testing/testcases.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/testing/testcases.py)
</details>

# ReviewBot Overview & System Architecture

## Purpose and Scope

Review Bot automates parts of the code review process by integrating a wide range of industry-standard static analysis and code checking tools with [Review Board](https://www.reviewboard.org/). It is designed to run external tools over the files attached to a review request, parse their output, and post the results back to Review Board as a review with comments. According to the project overview, Review Bot is **made for Review Board**, **scalable** (built on Celery), and **extensible** through a plugin API. Source: [README.rst:7-25]().

The repository is split into two independently distributed Python packages that work together:

| Package | Role |
| --- | --- |
| `reviewbot-extension` | A Review Board extension installed inside the Review Board server |
| `reviewbot-worker` | The worker process that executes the actual code checks |

Source: [bot/README.rst:11-23](), [extension/README.rst:9-19]().

## System Components

### Review Board Extension

The extension lives at `extension/reviewbotext/` and is loaded into Review Board. It surfaces the configuration UI used by administrators to select and parameterize code checking tools. The form layer in [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py) defines integration options such as `max_comments` (the upper bound on the number of comments a tool may post in a single review) and the new `notify_owner_only` flag added in 4.1 to restrict e-mail notifications to the review request owner. Source: [extension/reviewbotext/forms.py:38-65]().

### Worker

The worker is the execution engine. It is distributed as the `reviewbot-worker` Python package and is registered as console script `reviewbot-worker` in the package entry points. Source: [bot/setup.py:39-58](). The worker pulls tasks from a Celery broker, fetches the relevant files from Review Board via its HTTP API, dispatches them to a configured tool, and posts the resulting review back.

## High-Level Architecture

```mermaid
flowchart LR
    A[Review Board Server] -->|POST review request| B[Review Bot Extension]
    B -->|Schedule job via Celery| C[Celery Broker]
    C --> D[Review Bot Worker]
    D -->|Fetch files via API| A
    D -->|Invoke tool| E[Code Checking Tool]
    E -->|stdout / report| D
    D -->|Post review| A
    A -->|E-mail notification| F[Reviewer / Owner]
```

The worker is tool-agnostic: it loads any number of tool plugins that share a common base class. The package `entry_points` configuration registers each available tool under the `reviewbot.tools` group. Source: [bot/setup.py:39-58]().

## Tool Plugin Model

All tools inherit from `BaseTool`, which is re-exported from the convenience package `reviewbot.tools.base`. Three reusable mixins are also exported from that package and are commonly combined with `BaseTool`:

| Symbol | Purpose |
| --- | --- |
| `BaseTool` | Abstract base class defining the tool contract (file patterns, options, timeouts) |
| `FilePatternsFromSettingMixin` | Lets a tool derive its `file_patterns` from a comma-separated setting |
| `FullRepositoryToolMixin` | Provides checkout of a full repository, used by tools that need build context |
| `JavaToolMixin` | Helper for locating a Java tool on the system |

Source: [bot/reviewbot/tools/base/__init__.py:1-22]().

Tool authors subclass `BaseTool` (optionally with a mixin), declare class attributes such as `name`, `version`, `description`, `timeout`, `exe_dependencies`, and `file_patterns`, and implement `build_base_command` to construct the command line that is executed. Examples of declarative options can be seen in [bot/reviewbot/tools/clang.py:21-44]() for `Clang Static Analyzer`, [bot/reviewbot/tools/jshint.py:22-58]() for `JSHint`, and [bot/reviewbot/tools/cargotool.py:19-46]() for the `Cargo` tool. Each tool uses Django form fields (`django.forms.CharField`, `BooleanField`, `ChoiceField`, etc.) for its `options`, so the extension can render them automatically in the Review Board admin UI.

### Working With Full Repositories

Some tools (Clang, Cargo, Go, etc.) need a full source checkout to build or resolve imports. `FullRepositoryToolMixin` and the repository abstraction in [bot/reviewbot/repositories.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/repositories.py) handle this. `BaseRepository` is the base class and stores `name`, `clone_path`, and a local `repo_path` under the per-user data directory returned by `appdirs.site_data_dir('reviewbot')`. Source: [bot/reviewbot/repositories.py:30-58]().

## Configuration and Extensibility

The `entry_points` mechanism is the extension point for adding new tools. The shipped list registers 20 tools, covering languages such as C/C++ (`clang`, `cppcheck`, `cpplint`, `fbinfer`), Python (`flake8`, `pycodestyle`, `pydocstyle`, `pyflakes`, `doc8`), JavaScript (`jshint`), Java (`checkstyle`, `pmd`), Go (`gotool`, `gofmt`), Ruby (`rubocop`), Rust (`cargotool`, `rustfmt`), and shell scripts (`shellcheck`), plus a `rbsecretscanner` integration. Source: [bot/setup.py:39-58]().

Two additional layers complete the system:

- **Testing harness** — [bot/reviewbot/tools/testing/testcases.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/testing/testcases.py) exposes `tool_class`-driven helpers such as `_can_handle_file` so that tool authors can unit-test file filtering without spinning up the full worker.
- **Admin-side forms** — The extension form layer governs global options that apply across all tools, including `max_comments` and the 4.1-era `notify_owner_only` notification preference. Source: [extension/reviewbotext/forms.py:38-65]().

## Release History Notes

The most recent release tracked in the community evidence is Review Bot 4.1, which restored parsing for `cargo clippy`, `cargo test`, and other tools whose output formats had drifted, added a new e-mail notification option, and improved networking diagnostics. Review Bot 3.2, the prior release, focused on Review Board 5/6 compatibility and Secret Scanning enhancements. Both releases highlight the worker's role as the single integration point between arbitrary external tools and Review Board's review API. Source: [GitHub Release 4.1](https://github.com/reviewboard/ReviewBot/releases/tag/release-4.1), [GitHub Release 3.2](https://github.com/reviewboard/ReviewBot/releases/tag/release-3.2).

## See Also

- [Review Bot Documentation](https://www.reviewboard.org/docs/reviewbot/latest/)
- [Review Board Integrations](https://www.reviewboard.org/docs/manual/latest/admin/integrations/)
- [Celery Documentation](https://docs.celeryq.dev/)
- Related projects: [RBTools](https://github.com/reviewboard/rbtools/), [RB Gateway](https://github.com/reviewboard/rb-gateway/)

---

<a id='page-2'></a>

## Supported Code Checking Tools & Configuration

### Related Pages

Related topics: [ReviewBot Overview & System Architecture](#page-1), [Development, Extensibility & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [bot/reviewbot/tools/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/__init__.py)
- [bot/reviewbot/tools/base/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/__init__.py)
- [bot/reviewbot/tools/base/tool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/tool.py)
- [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py)
- [bot/reviewbot/tools/clang.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/clang.py)
- [bot/reviewbot/tools/jshint.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/jshint.py)
- [bot/reviewbot/tools/checkstyle.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/checkstyle.py)
- [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py)
- [bot/reviewbot/tools/utils/codeclimate.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/utils/codeclimate.py)
- [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py)
- [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py)
</details>

# Supported Code Checking Tools & Configuration

## Overview

Review Bot is an automated code-review worker that wraps a wide range of industry-standard static analysis and linting tools and surfaces their output as Review Board comments. Tools are pluggable Python classes registered through setuptools entry points and executed asynchronously by a Celery-based worker. Configuration is supplied by administrators through Review Board's built-in Integrations UI and passed to each tool at run time via the `settings` dictionary on the tool instance.

The user-facing list of supported tools is documented in the project README, grouped by language family (C/C++, Go, Java, JavaScript, Python, Ruby, Rust, Shell Scripts). Each tool name in that list maps to a Python entry point declared in `bot/setup.py`, which is how the worker discovers and loads the class. As noted in the 4.1 release notes, several tools (such as `cargo clippy`) had to be updated because upstream changes in their output format caused "parsing issues and garbled comments" in earlier versions — keeping the registered class list aligned with current tool behavior is therefore part of normal maintenance.

## Tool Architecture: BaseTool and Mixins

Every code-checking tool in Review Bot inherits from `BaseTool` (defined in [bot/reviewbot/tools/base/tool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/tool.py)), which provides the common lifecycle hooks and class-level metadata. The `BaseTool` class declares class attributes that subclasses override to describe themselves:

- `name` — the human-readable name shown in the Integrations UI.
- `description` — a short summary of what the tool checks.
- `version` — a compatibility version string; bumping it is treated as a breaking change for existing integrations.
- `exe_dependencies` — a list of executable names that must be available on `PATH` for the tool to run (the worker uses `is_exe_in_path` to verify).
- `file_patterns` — glob patterns matched against filenames to decide whether a file should be checked.
- `options` — a list of dictionaries describing the form fields exposed in the integration configuration UI.

To reduce boilerplate, `BaseTool` is composed with mixins exported from [bot/reviewbot/tools/base/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/__init__.py):

- `FilePatternsFromSettingMixin` — derives file patterns from user-supplied settings (a comma-separated list of extensions or globs), falling back to the class default. Source: [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py).
- `FullRepositoryToolMixin` — used by tools that must analyze the entire repository at once (e.g. Clang).
- `JavaToolMixin` — supplies JVM execution plumbing for Java-based tools.

The re-exports in [bot/reviewbot/tools/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/__init__.py) make `BaseTool` the canonical import for any plugin author.

```mermaid
classDiagram
    class BaseTool {
      +name: str
      +description: str
      +version: str
      +exe_dependencies: list
      +file_patterns: list
      +options: list
      +handle_file()
    }
    class FilePatternsFromSettingMixin
    class FullRepositoryToolMixin
    class JavaToolMixin
    class JSHintTool
    class ClangTool
    class CheckstyleTool
    BaseTool <|-- JSHintTool
    BaseTool <|-- ClangTool
    BaseTool <|-- CheckstyleTool
    FilePatternsFromSettingMixin <|-- JSHintTool
    FullRepositoryToolMixin <|-- ClangTool
    JavaToolMixin <|-- CheckstyleTool
```

## Configuring Tools

### Per-tool options

Each tool's `options` list is rendered by the Review Bot extension into a Django form. A typical entry, as seen in [bot/reviewbot/tools/jshint.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/jshint.py), has the shape:

```python
{
    'name': 'extra_ext_checks',
    'field_type': 'django.forms.CharField',
    'default': '',
    'field_options': {
        'label': 'Extra file extensions',
        'help_text': 'A comma-separated list of extra file extensions to check.',
        'required': False,
    },
}
```

The same convention is used in [bot/reviewbot/tools/clang.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/clang.py) (`cmdline_args`) and [bot/reviewbot/tools/checkstyle.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/checkstyle.py) (a `CharField` with a `Textarea` widget for XML configuration). The `default` and `help_text` keys flow into the admin form, while `field_type` and `field_options` map directly to Django form-field constructors.

### File patterns

`FilePatternsFromSettingMixin` lets administrators add file types without editing source code. For JSHint, the default `file_patterns = ['*.js']` is augmented by the user-supplied `extra_ext_checks` setting, which is parsed into a comma-separated list (using the project's `split_comma_separated` helper in [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py)). Pattern matching itself is done with `fnmatchcase` from the standard library, so globs are case-sensitive and Unix-style.

### Worker-level settings

Beyond per-tool options, the extension exposes integration-wide settings. The maximum number of comments per review (`MAX_COMMENTS_DEFAULT`) caps how many diff comments a single run can produce, with a warning surfaced when the cap is exceeded (Source: [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py)). As of Review Bot 4.1, a new `notify_owner_only` boolean was added to the configuration form and to the corresponding `to_owner_only` field on the review-resource WebAPI; when set, e-mail notifications for tool-generated reviews are sent only to the owner of the review request (Source: [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py)).

## Registered Tools

Tools are wired into the worker through the `reviewbot.tools` entry-point group declared in [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py). Each line maps a short key to a fully qualified class name. The currently shipped tools include:

| Entry point | Class | Notes |
|---|---|---|
| `cargotool` | `reviewbot.tools.cargotool:CargoTool` | Rust (`cargo`); updated in 4.1 |
| `checkstyle` | `reviewbot.tools.checkstyle:CheckstyleTool` | Java |
| `clang` | `reviewbot.tools.clang:ClangTool` | C/C++/Obj-C, full-repo |
| `cppcheck` | `reviewbot.tools.cppcheck:CPPCheckTool` | C/C++ |
| `cpplint` | `reviewbot.tools.cpplint:CPPLintTool` | C++ style |
| `doc8` | `reviewbot.tools.doc8:Doc8Tool` | ReST docs |
| `fbinfer` | `reviewbot.tools.fbinfer:FBInferTool` | Java/Obj-C |
| `flake8` | `reviewbot.tools.flake8:Flake8Tool` | Python wrapper |
| `gofmt` | `reviewbot.tools.gofmt:GofmtTool` | Go |
| `gotool` | `reviewbot.tools.gotool:GoTool` | `go vet`, `go test` |
| `jshint` | `reviewbot.tools.jshint:JSHintTool` | JavaScript |
| `pmd` | `reviewbot.tools.pmd:PMDTool` | Multi-language |
| `pycodestyle` | `reviewbot.tools.pycodestyle:PycodestyleTool` | Python |
| `pydocstyle` | `reviewbot.tools.pydocstyle:PydocstyleTool` | Python docstrings |
| `pyflakes` | `reviewbot.tools.pyflakes:PyflakesTool` | Python |
| `rbsecretscanner` | `reviewbot.tools.rbsecretscanner:SecretScannerTool` | Secret scanning (3.2 enhancements) |
| `rubocop` | `reviewbot.tools.rubocop:RubocopTool` | Ruby |
| `rustfmt` | `reviewbot.tools.rustfmt:RustfmtTool` | Rust |
| `shellcheck` | `reviewbot.tools.shellcheck:ShellCheckTool` | Shell |

Tools that emit CodeClimate-formatted JSON share `add_comment_from_codeclimate_issue` from [bot/reviewbot/tools/utils/codeclimate.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/utils/codeclimate.py), which converts the `location.positions` block into a Review Board diff comment with `first_line`, `num_lines`, `start_column`, and `error_code` populated from the payload. Test scaffolding for new tools lives in [bot/reviewbot/tools/testing/testcases.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/testing/testcases.py), which provides a metaclass-driven base class that auto-splits simulation and integration tests.

## See Also

- [README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst) — full list of supported tools grouped by language.
- [Review Bot documentation](https://www.reviewboard.org/docs/reviewbot/latest/) — installation and configuration guides.
- [Review Bot 4.1 release notes](https://github.com/reviewboard/ReviewBot/releases/tag/release-4.1) — recent tool-format compatibility updates.

---

<a id='page-3'></a>

## Deployment & Infrastructure

### Related Pages

Related topics: [ReviewBot Overview & System Architecture](#page-1), [Development, Extensibility & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst)
- [bot/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/bot/README.rst)
- [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py)
- [extension/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/setup.py)
- [extension/reviewbotext/integration.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/integration.py)
- [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py)
- [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py)
- [bot/reviewbot/repositories.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/repositories.py)
- [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py)
</details>

# Deployment & Infrastructure

Review Bot is distributed as two cooperating Python packages that together form an automated code review pipeline for Review Board. Understanding how these packages are packaged, installed, and wired together is essential for any deployment.

## Package Architecture

Review Bot is split into two independently installable components, each with its own `setup.py` and PyPI distribution. This separation lets administrators scale the worker independently from the Review Board web service that hosts the extension.

| Package | PyPI Name | Role | Key Dependencies |
| --- | --- | --- | --- |
| `bot/` | `reviewbot-worker` | Runs tools, processes review payloads, posts reviews back to Review Board | Review Board Python API client, per-tool executables |
| `extension/` | `ReviewBotExtension` | Installs inside the Review Board site; receives review triggers and serves configuration UI | `celery~=5.3`, Django form widgets, Djblets integrations |

Source: [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py) and [extension/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/setup.py). The README explicitly distinguishes the `Review Bot extension` and `Review Bot worker` packages and links to their PyPI pages ([README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst)).

Both packages declare `python_requires='>=3.8'` and advertise support for Python 3.8 through 3.13 in their classifiers ([bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py), [extension/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/setup.py)). The license is MIT, and both are classified as Production/Stable.

## Runtime Topology

```mermaid
flowchart LR
    RR[Review Request Published] --> EXT[ReviewBotExtension<br/>in Review Board]
    EXT -->|enqueues| WORKER[reviewbot-worker]
    WORKER -->|clones| REPO[Repository Backend]
    WORKER -->|invokes| TOOL[Tool Executables]
    TOOL -->|stdout/stderr| WORKER
    WORKER -->|POST /reviews/| EXT
    EXT -->|notification| OWNER[Review Request Owner]
```

The extension listens for two Review Board signals: `review_request_published` and `status_update_request_run`. It uses `SignalHook` from Djblets to dispatch them to handler methods on the integration. Source: [extension/reviewbotext/integration.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/integration.py). When a matching review request is published, the extension schedules work; the worker then fetches the diff, checks out the repository, runs configured tools, and posts a review back through the web API.

## Installation Surfaces

Because the worker spawns external executables for each tool (for example `clang` for the Clang tool, `cargo` and `cargo-clippy` for the CargoTool, `jshint` for JSHint), each host running the worker must have the relevant binaries on the `PATH` or configured via Review Bot's `exe_paths` setting. Source: [bot/reviewbot/tools/clang.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/clang.py), [bot/reviewbot/tools/cargotool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/cargotool.py), [bot/reviewbot/tools/jshint.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/jshint.py). Each tool declares its dependencies in an `exe_dependencies` list and resolves the absolute path via `config['exe_paths'][...]`.

For tools that need the full repository (such as the Clang analyzer and CargoTool), the worker uses a `FullRepositoryToolMixin`. The repository backend implementation uses `appdirs.site_data_dir('reviewbot')` to determine where to store per-repository clones, ensuring the data directory follows OS conventions (XDG on Linux, `Library/Application Support` on macOS, `%APPDATA%` on Windows). Source: [bot/reviewbot/repositories.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/repositories.py).

## Configuration and Operational Notes

Operator-facing configuration is exposed through a Django integration form (`ReviewBotConfigForm`) registered with the extension. The form lets administrators select which tools to run, configure per-tool options (as `CharField`, `BooleanField`, and `ChoiceField` widgets), and set a hard cap on the number of comments a single review may produce. Source: [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py). Recent releases have added new options here; for example, Review Bot 4.1 introduced a `notify_owner_only` toggle that, when enabled, restricts review e-mail notifications to the review request owner rather than all subscribers. Source: [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py), [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py) (where the matching `to_owner_only` API parameter is declared with `added_in: '4.1'`).

The extension also serves a web API endpoint for creating reviews. The `create` handler accepts review bodies (`body_top`, `body_bottom`), diff comments, general comments, and the new `to_owner_only` flag, then publishes the review on behalf of the configured bot user. Source: [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py).

For tool authors and operators extending the system, the codebase provides a mixin, `FilePatternsFromSettingMixin`, that lets a tool accept a comma-separated list of additional file extensions or glob patterns at runtime instead of relying solely on the hard-coded `file_patterns` list. Source: [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py).

## Failure Modes and Compatibility

The community release notes highlight two recurring operational concerns. First, tool output formats change frequently — the 4.1 release notes mention restoring correct parsing for `cargo clippy` and `cargo` after upstream output changes produced garbled comments. Second, Review Board major-version compatibility is a moving target; release 3.2 explicitly noted improvements for Review Board 5 and 6. Operators upgrading Review Board should check the Review Bot release notes for the matching compatibility fixes before deploying.

Because the worker relies on per-tool binaries, a deployment should pin tool versions alongside the worker version, and treat any tool upgrade as a potentially breaking change to the review output pipeline.

## See Also

- [README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst) — project overview and tool index
- [bot/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/bot/README.rst) — worker-specific documentation
- [extension/reviewbotext/integration.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/integration.py) — signal hooks and integration lifecycle
- [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py) — review-creation web API

---

<a id='page-4'></a>

## Development, Extensibility & Operations

### Related Pages

Related topics: [ReviewBot Overview & System Architecture](#page-1), [Supported Code Checking Tools & Configuration](#page-2), [Deployment & Infrastructure](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.rst](https://github.com/reviewboard/ReviewBot/blob/main/README.rst)
- [bot/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/bot/README.rst)
- [extension/README.rst](https://github.com/reviewboard/ReviewBot/blob/main/extension/README.rst)
- [bot/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/setup.py)
- [extension/setup.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/setup.py)
- [bot/reviewbot/tools/clang.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/clang.py)
- [bot/reviewbot/tools/cargotool.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/cargotool.py)
- [bot/reviewbot/tools/jshint.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/jshint.py)
- [bot/reviewbot/tools/base/mixins.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/mixins.py)
- [bot/reviewbot/tools/testing/testcases.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/testing/testcases.py)
- [bot/reviewbot/processing/review.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/processing/review.py)
- [bot/reviewbot/repositories.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/repositories.py)
- [bot/reviewbot/tools/utils/codeclimate.py](https://github.com/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/utils/codeclimate.py)
- [extension/reviewbotext/integration.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/integration.py)
- [extension/reviewbotext/forms.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/forms.py)
- [extension/reviewbotext/resources.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/resources.py)
- [extension/reviewbotext/compat/__init__.py](https://github.com/reviewboard/ReviewBot/blob/main/extension/reviewbotext/compat/__init__.py)
</details>

# Development, Extensibility & Operations

Review Bot is organized as two cooperating Python packages distributed via PyPI: the Review Board **extension** (`reviewbot-extension`) that runs inside the Review Board web process, and the standalone **worker** (`reviewbot-worker`) that consumes queued jobs and executes code-checking tools. The split keeps the heavy lifting off the web server while letting administrators configure tools through the standard Review Board admin UI (Source: [README.rst:1-30](), [bot/README.rst:1-15](), [extension/README.rst:1-15]()).

## Two-Package Architecture

The top-level `README.rst` advertises both halves — `reviewbot-extension` and `reviewbot-worker` — as installable components, and each subproject ships its own `setup.py` declaring an identical supported-Python range (3.8 through 3.13) and a matching MIT-licensed, Review Board-framework classifier profile (Source: [bot/setup.py:6-15](), [extension/setup.py:9-18]()). The extension side depends on `celery~=5.3` to dispatch work, while the worker is a pure consumer of those tasks (Source: [extension/setup.py:5-7]()).

```mermaid
flowchart LR
    A[Review Board Server] -->|runs| B(reviewbot-extension)
    B -->|queues tasks| C[Celery Broker]
    C -->|delivers jobs| D(reviewbot-worker)
    D -->|invokes| E[BaseTool subclass]
    E -->|HTTP API| A
```

At runtime, the extension installs a `ReviewBotIntegration` that connects to the `review_request_published` and `status_update_request_run` signals (Source: [extension/reviewbotext/integration.py:40-55]()). When a matching event fires, the integration enqueues a job; the worker, connected to the same broker, picks it up, runs the configured tools, and posts the resulting review back through the Review Board Web API (Source: [extension/reviewbotext/resources.py:30-60]()).

## Extending Review Bot with New Tools

A new code-checking tool is added by subclassing `BaseTool` in `bot/reviewbot/tools/`. The base contract requires four declarative attributes — `name`, `version`, `description`, and a list of `exe_dependencies` the worker must verify before invocation. `ClangTool` illustrates the pattern, declaring `exe_dependencies = ['clang']` and restricting its work to `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.c++`, `*.m`, and `*.mm` (Source: [bot/reviewbot/tools/clang.py:18-35]()). For tools that need access to a full source tree, the `FullRepositoryToolMixin` adds cloning logic so the tool can `cargo build` or `rustc` against the whole project (Source: [bot/reviewbot/tools/cargotool.py:21-30]()).

User-configurable options are declared as a list of Django-style field descriptors. `CargoTool` exposes `clippy` and `test` toggles built on `django.forms.BooleanField` (Source: [bot/reviewbot/tools/cargotool.py:33-58]()), while `ClangTool` adds a free-form `cmdline_args` text field whose value is read inside `build_base_command` (Source: [bot/reviewbot/tools/clang.py:37-50]()). Tools that benefit from glob-based file filtering can mix in `FilePatternsFromSettingMixin`, which lets administrators override extensions and patterns from the admin UI (Source: [bot/reviewbot/tools/base/mixins.py:25-50](), [bot/reviewbot/tools/jshint.py:25-40]()).

Tools post results back to Review Board by calling comment helpers on a `reviewbot.processing.review.File` object. Shared utilities such as `add_comment_from_codeclimate_issue` translate a CodeClimate JSON payload into a positioned diff comment (Source: [bot/reviewbot/tools/utils/codeclimate.py:10-25]()). The `BaseCommentData`, `GeneralCommentData`, and `DiffCommentData` typed dictionaries describe the structure of comment payloads that the extension's Web API endpoint accepts (Source: [bot/reviewbot/processing/review.py:25-60]()).

## Testing, Configuration, and Operational Concerns

The worker ships a test harness in `bot/reviewbot/tools/testing/testcases.py`. `ToolTestCaseMetaclass` splits any method marked as a simulation or integration test into individual test cases, and asserts that subclasses provide the required `tool_class`, `tool_exe_config_key`, and `tool_exe_path` attributes when the tool declares executable dependencies (Source: [bot/reviewbot/tools/testing/testcases.py:20-45]()). This makes it straightforward to write tests that run the tool against a fake binary without depending on host installations.

On the extension side, `ReviewBotConfigForm` is the primary operations surface. It exposes tool selection, the `max_comments` ceiling (with explanatory help text warning about browser performance when set too high), and — new in 4.1 — a `notify_owner_only` BooleanField that scopes review e-mail notifications to the review request owner (Source: [extension/reviewbotext/forms.py:10-30]()). The matching `to_owner_only` field on the `reviews` Web API resource is documented with `added_in: '4.1'` and is threaded through the `create` method (Source: [extension/reviewbotext/resources.py:35-55]()). These two changes are the most visible operational improvements in the 4.1 release line and align with the release notes' emphasis on better notification control.

Repository access is abstracted through `BaseRepository` in `bot/reviewbot/repositories.py`, which records the Review Board `tool_name` and a `repo_types` tuple so SCM-specific backends (Git, Mercurial, etc.) can be plugged in without changing the tool layer (Source: [bot/reviewbot/repositories.py:20-50]()). Finally, `extension/reviewbotext/compat/__init__.py` is the designated landing spot for compatibility shims that smooth over differences between Review Board 5 and 6, matching the 3.2 release notes' focus on cross-version support (Source: [extension/reviewbotext/compat/__init__.py:1-10]()).

## Compatibility and Deployment Matrix

Both packages share the same Python 3.8–3.13 support window and the same Review Board-framework classifier profile, which simplifies rolling upgrades (Source: [bot/setup.py:6-15](), [extension/setup.py:9-18]()). Operators can install the extension directly from PyPI or pull official Docker images referenced in the top-level README. Community reports around the 4.1 release highlight that several tools — notably `cargo clippy` and `cargo test` — have changed their output format in recent versions, so workers upgrading into the 4.x line should expect parser fixes for "garbled comments" regressions to ship with the upgrade. When extending Review Bot, the safe pattern is to keep parsing code in dedicated helpers, gate behavior behind `exe_dependencies`, and ship a matching test case in the worker's test suite so future tool-version churn is contained.

## See Also

- [Architecture & Components](architecture.md)
- [Tool Reference](tools.md)
- [Configuration & Deployment](configuration.md)
- [Review Bot 4.1 Release Notes](https://github.com/reviewboard/ReviewBot/releases/tag/release-4.1)
- [Review Bot 3.2 Release Notes](https://github.com/reviewboard/ReviewBot/releases/tag/release-3.2)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: reviewboard/ReviewBot

Summary: Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

## 1. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/reviewboard/ReviewBot

## 2. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/reviewboard/ReviewBot

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/reviewboard/ReviewBot

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

<!-- canonical_name: reviewboard/ReviewBot; human_manual_source: deepwiki_human_wiki -->