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

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 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.

# 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.

# 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) extracts changes in three modes: workspace, commit, or range.
3. File Filter (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) 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) summarizes older conversation rounds when the message buffer exceeds token budgets.
6. Output Writer (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 – Entry point for the CLI.
• cmd/opencodereview/review_cmd.go – Parses ocr review flags and initializes the agent.
• internal/agent/agent.go – Core orchestration, sub-task dispatch, and main control loops.
• internal/agent/preview.go – Contains the whyExcluded five-gate filter logic.
• 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 – 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:

   git fetch upstream
   git checkout main
   git merge upstream/main

2. Create and push your branch:

   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 and filtering in 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}