# How to Contribute to the Development of OpenCodeReview: A Complete Guide

> Contribute to open-code-review development. Fork the Alibaba repo, set up Go 1.25+, follow Conventional Commits, and submit a PR passing make test and CLA checks. Start contributing today!

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-04

---

**To contribute to the development of open-code-review, fork the Alibaba repository, set up Go 1.25+ and GNU Make, follow the Conventional Commits specification, and submit a pull request that passes `make test` and the CLA check.**

OpenCodeReview is Alibaba's open-source AI-driven code review CLI written in Go. Contributing to this project involves more than just submitting code; you must understand the agent-based architecture and adhere to the strict workflow defined in [`CONTRIBUTING.md`](https://github.com/alibaba/open-code-review/blob/main/CONTRIBUTING.md) to ensure your changes integrate seamlessly with the LLM orchestration pipeline.

## Setting Up Your Development Environment

Before writing code, you must configure your local workspace and verify the toolchain.

### Fork and Clone the Repository

Start by creating your own fork on GitHub, then clone it locally and add the upstream remote to keep your branch synchronized.

```bash

# Clone your fork (replace <your-username> with your GitHub handle)

git clone https://github.com/<your-username>/open-code-review.git
cd open-code-review

# Add the upstream remote to fetch official updates

git remote add upstream https://github.com/alibaba/open-code-review.git

```

### Install Prerequisites and Build

OpenCodeReview requires **Go 1.25+**, Git, and GNU Make. Verify your installation by building the binary and running the test suite, which includes race detection.

```bash

# Build the ocr binary

make build

# Run all tests including race detection

make test

```

Successful execution of `make test` confirms your environment can compile the project and pass the CI checks required for pull request acceptance.

## Understanding the OpenCodeReview Architecture

Meaningful contributions require familiarity with the review pipeline. The flow moves from diff extraction through file filtering to LLM agent orchestration.

### The Review Pipeline Flow

When a user runs `ocr review`, the execution follows this path:

1. **Bootstrap** initializes the configuration.
2. **Diff Provider** ([`internal/diff/git.go`](https://github.com/alibaba/open-code-review/blob/main/internal/diff/git.go)) extracts changes in three modes: workspace, commit, or range.
3. **File Filter** ([`internal/agent/preview.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/preview.go)) applies a five-gate exclusion check (`whyExcluded`) based on binary status, user patterns, supported extensions, and test-file heuristics.
4. **Subtask Dispatch** ([`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)) spawns goroutines for each remaining file, optionally running a plan phase followed by a main tool-use loop.
5. **Memory Compression** ([`internal/agent/compression.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/compression.go)) summarizes older conversation rounds when the message buffer exceeds token budgets.
6. **Output Writer** ([`cmd/opencodereview/output.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/output.go)) post-processes `code_comment` calls, re-anchors them, filters duplicates, and renders text or JSON.

### Key Packages and Entry Points

Locate logic correctly by understanding the repository structure:

- **[`cmd/opencodereview/main.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/main.go)** – Entry point for the CLI.
- **[`cmd/opencodereview/review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go)** – Parses `ocr review` flags and initializes the agent.
- **[`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)** – Core orchestration, sub-task dispatch, and main control loops.
- **[`internal/agent/preview.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/preview.go)** – Contains the `whyExcluded` five-gate filter logic.
- **[`internal/diff/git.go`](https://github.com/alibaba/open-code-review/blob/main/internal/diff/git.go)** – Git diff extraction supporting workspace, commit, and range modes.
- **`internal/tool/`** – Built-in tools like `code_search`, `file_read_diff`, and `file_find`.
- **[`internal/config/template/task_template.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/task_template.json)** – LLM prompt templates.

## Contribution Workflow and Coding Standards

OpenCodeReview enforces strict conventions to maintain consistency across the Go codebase.

### Branch Naming Conventions

Create feature branches from the latest `main` using specific prefixes:

- `feat/` – New features or tools
- `fix/` – Bug fixes
- `docs/` – Documentation updates
- `refactor/` – Code restructuring without behavior changes
- `test/` – Test additions or fixes
- `chore/` – Maintenance tasks

Example: `git checkout -b feat/add-custom-tool`

### Code Style and Testing Requirements

All contributions must follow Go formatting standards and include adequate test coverage.

- **Formatting**: Run `go fmt ./...` and `go vet ./...` before committing.
- **Commit Messages**: Follow the Conventional Commits format: `type(scope): short summary` (e.g., `feat(agent): add compression threshold`).
- **Testing**: Add or update unit tests in `internal/*_test.go` files. The project uses the standard Go testing framework.

## Submitting Your First Pull Request

Once your feature is implemented and tested, submit it for review.

1. **Sync your fork** with upstream to avoid merge conflicts:

   ```bash
   git fetch upstream
   git checkout main
   git merge upstream/main
   ```

2. **Create and push your branch**:

   ```bash
   git checkout -b feat/your-feature-name
   git push origin feat/your-feature-name
   ```

3. **Open a Pull Request** against `alibaba/open-code-review:main`. The PR template requires you to describe what the change does and why it is needed.
4. **Sign the CLA**: First-time contributors must sign the Alibaba Open Source Contributor License Agreement via the bot link that appears in the PR comments.
5. **Address review feedback**: Maintainers may request changes before merging.

## Summary

- Fork the repository and add the upstream remote to synchronize with the official `alibaba/open-code-review` repository.
- Install Go 1.25+, Git, and GNU Make, then verify your setup with `make build` and `make test`.
- Study the agent architecture in `internal/agent/` before modifying core review logic, particularly the orchestration in [`agent.go`](https://github.com/alibaba/open-code-review/blob/main/agent.go) and filtering in [`preview.go`](https://github.com/alibaba/open-code-review/blob/main/preview.go).
- Use Conventional Commits and branch prefixes like `feat/` or `fix/` to categorize your changes.
- Sign the Alibaba CLA when submitting your first pull request to complete the contribution process.

## Frequently Asked Questions

### What are the minimum system requirements to contribute to OpenCodeReview?

You need Go version 1.25 or higher, Git, and GNU Make installed on your system. The project relies on standard Go tooling and requires the ability to run race detection tests via `make test`.

### How does the file filtering logic decide which diffs to review?

The five-gate filter implemented in [`internal/agent/preview.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/preview.go) (function `whyExcluded`) excludes files that are binary, match user-defined exclude patterns, have unsupported extensions, or match built-in test-file patterns. Only files passing all five gates proceed to the LLM agent.

### Where should I add new tools for the code review agent?

Add new tool implementations in the `internal/tool/` directory, following the pattern of existing tools like `code_search` and `file_read_diff`. You must also update the subtask dispatch logic in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) if your tool requires special handling in the plan or main loops.

### What happens if I don't sign the CLA before submitting my first pull request?

The pull request will be blocked from merging. A bot will automatically comment on your PR with a link to the Alibaba Open Source Contributor License Agreement, which you must sign electronically before the maintainers can review and merge your code.