alibaba__open-code-review/CONTRIBUTING.md

Contributing to OpenCodeReview

Thank you for your interest in contributing to OpenCodeReview! Every contribution matters — whether it's fixing a typo, reporting a bug, or implementing a new feature.

简体中文版 | 日本語版 | 한국어 | Русский

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. Please be kind and constructive in all interactions.

Ways to Contribute

There are many ways to contribute beyond writing code:

• Report bugs — Found something broken? Open an issue with reproduction steps.
• Suggest features — Have an idea for improvement? You can start a conversation in GitHub Discussions or open a Feature Request issue.
• Improve documentation — Fix typos, clarify explanations, or add examples. You can also open a Documentation Issue to report problems.
• Review pull requests — Help us review code from other contributors.
• Write code — Fix bugs, add features, or improve performance.

Getting Started

Prerequisites

• Go 1.25+
• Git
• Make

Setup

# 1. Fork the repository on GitHub

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

# 3. Add upstream remote (for syncing updates from the main repo)
git remote add upstream https://github.com/alibaba/open-code-review.git

# 4. Build the project
make build

# 5. Run tests
make test

If everything passes, you're ready to contribute.

Note: The upstream remote is read-only for contributors — it is used to pull the latest changes from the main repository. You cannot push directly to upstream. All commits must be pushed to your fork (origin) and submitted via Pull Request.

Line Endings

This project enforces LF line endings via .gitattributes. Configure Git to normalize line endings automatically:

git config core.autocrlf input

This ensures any CRLF is converted to LF on commit, preventing line-ending issues in CI.

Development Workflow

Branching

Create a feature branch from main:

git checkout main
git pull upstream main
git checkout -b feat/your-feature-name

Use prefixes to indicate the type of change:

Prefix	Purpose
feat/	New feature
fix/	Bug fix
docs/	Documentation only
refactor/	Code refactoring (no behavior change)
test/	Adding or updating tests
chore/	Build, CI, or tooling changes

Commit Messages

Follow Conventional Commits format:

<type>(<scope>): <short summary>

[optional body]

Examples:

feat(agent): add support for custom tool definitions
fix(llm): handle timeout errors in Anthropic API calls
docs(README): update configuration examples

License Headers

Every source file (.go, .sh, .js, .mjs, .ts, .tsx) must include an SPDX license header. After creating new files, run:

make license-add

This automatically adds the required header. CI will reject PRs with missing headers.

Code Quality

Before submitting your changes, make sure they pass all checks:

# Format, lint, and verify license headers
make check

# Run tests with race detection
make test

# Build successfully
make build

Project Structure

├── cmd/opencodereview/   # CLI entry point
├── internal/
│   ├── agent/            # Review agent logic
│   ├── config/           # Configuration management
│   ├── diff/             # Git diff parsing
│   ├── llm/              # LLM API client (Anthropic & OpenAI)
│   ├── model/            # Data models
│   ├── session/          # Review session management
│   ├── tool/             # Built-in tools (file_read, code_search, etc.)
│   ├── telemetry/        # OpenTelemetry integration
│   └── viewer/           # WebUI session viewer
├── pages/                # WebUI frontend
├── scripts/              # Build & install scripts
└── bin/                  # NPM wrapper

AI-Assisted Development

Using AI to help with your development is perfectly welcome, and we are glad if it makes contributing easier. What we cannot accept is code that a model produced going straight into a commit unread, with none of its redundancy or mistakes cleaned up. Submissions like that slow down the review conversation and make a pull request harder to move forward.

If AI played a part in how you worked, please follow the rules below.

Rules:

1. You must disclose in your initial issue or pull request that you used AI/LLM, as well as the tools/models you used.
2. You should understand every line of code written by AI and know what the AI did.
3. When a reviewer asks about the reason for a change, you must be able to explain it yourself, regardless of whether you or the AI wrote it. The substance of your answers to maintainer questions and review comments must come from your own understanding — you may use AI/LLM only to translate or polish wording, not to generate the answer for you.
4. Your PR should not contain repeated cycles like AI generated -> fixed -> fixed -> fixed. This may indicate that you did not review the AI-generated code, but instead let the AI fix issues as they arise, over and over.
5. You must review all code, text, and other content generated by AI/LLM yourself before proactively requesting a review from any member.
6. You must not attribute commits to AI/LLM, including through "Assisted-by", "Co-developed-by", or similar trailers.
7. Do not write overly long commit messages. Important information should go in the PR description rather than in collapsed commit messages.
8. If you are unwilling or unable to do all of the above, please close your issue or pull request.

Thanks!

Contributing to Documentation

Documentation is a crucial part of OpenCodeReview. We welcome improvements to README files, inline code comments, configuration examples, and any user-facing text.

What Counts as a Documentation Contribution

• Fixing typos, grammar errors, or broken links
• Clarifying confusing explanations or adding missing context
• Adding usage examples for commands or configuration options
• Updating outdated content (e.g., after a feature change)
• Translating or improving localized documentation (README.zh-CN.md, README.ja-JP.md, README.ko-KR.md, README.ru-RU.md, CONTRIBUTING.zh-CN.md, CONTRIBUTING.ja-JP.md, CONTRIBUTING.ko-KR.md, CONTRIBUTING.ru-RU.md)

Documentation Workflow

1. If you spot an issue but don't plan to fix it yourself, open a Documentation Issue.
2. If you'd like to fix it, fork the repo, make your changes, and submit a PR with the docs/ branch prefix (e.g., docs/fix-config-example).
3. Documentation-only PRs don't require test changes, but please verify that any commands or code snippets you include are accurate.

Documentation Files

File	Purpose
README.md	Main project documentation (English)
README.zh-CN.md	Chinese translation
README.ja-JP.md	Japanese translation
README.ko-KR.md	Korean translation
README.ru-RU.md	Russian translation
CONTRIBUTING.md	Contribution guide (English)
CONTRIBUTING.zh-CN.md	Contribution guide (Chinese)
CONTRIBUTING.ja-JP.md	Contribution guide (Japanese)
CONTRIBUTING.ko-KR.md	Contribution guide (Korean)
CONTRIBUTING.ru-RU.md	Contribution guide (Russian)

Submitting Changes

Opening an Issue

Before working on a significant change, please open an issue first to discuss the approach. This prevents duplicate work and ensures your contribution aligns with the project's direction.

When reporting a bug, include:

1. OpenCodeReview version (ocr version)
2. OS and architecture
3. Steps to reproduce
4. Expected vs. actual behavior
5. Relevant logs or error messages

Pull Request Process

1. Keep PRs focused — One logical change per PR. If you have multiple independent changes, submit separate PRs.
2. Write tests — Add or update tests for any behavior changes.
3. Update docs — If your change affects user-facing behavior, update the relevant documentation.
4. Sign the CLA — All contributors must sign the Contributor License Agreement before their PR can be merged (see below).
5. Fill in the PR template — Describe what your change does and why.

PR Title Format

Use the same Conventional Commits format as commit messages:

feat(agent): add support for custom tool definitions

Review Process

• A maintainer will review your PR, usually within a few business days.
• We may request changes — this is normal and collaborative, not adversarial.
• Once approved, a maintainer will merge your PR.

Tips for Faster PR Reviews

Want your PR to be reviewed and merged quickly? These practices help:

• Sign the CLA early — Many first-time contributors get blocked because they miss the CLA bot comment. Sign the Contributor License Agreement as soon as the bot prompts you — your PR cannot be merged without it.
• Ensure all CI checks pass — PRs with failing checks will not be reviewed. Run make test and make build locally before pushing to catch issues early.
• Keep changes focused and small — A PR that does one thing well is far easier to review than one that mixes unrelated changes. Smaller PRs get reviewed faster and are less likely to require multiple rounds of revision.
• Write a clear, accurate description — Explain what changed and why. The description must reflect the actual diff — reviewers lose trust when the two don't match. If the scope shifted during development, update the description before requesting review.
• Include tests for behavior changes — New features or bug fixes without tests raise questions. Tests demonstrate correctness and help reviewers understand the intended behavior.
• Follow existing code patterns — Match the style, naming conventions, and architecture of the surrounding code. Consistency reduces cognitive load for reviewers and avoids style-only review comments.
• Respond to feedback promptly — When a reviewer requests changes, address them quickly to keep the review cycle short. If you disagree, explain your reasoning rather than ignoring the comment.

Contributor License Agreement (CLA)

We require all contributors to sign the Alibaba Open Source Contributor License Agreement before we can merge your contributions. This ensures that the project can be distributed under its license terms.

When you open your first PR, a CLA bot will post a comment with instructions. Simply follow the link to sign electronically — it only takes a minute.

First-Time Contributors

New to the project? Look for issues labeled:

• good first issue — Small, well-scoped tasks ideal for getting started.
• help wanted — Issues where we'd appreciate community help.

Some good areas to start:

• Improving error messages and CLI output
• Writing tests for untested code paths
• Documentation improvements

Community

• Bug Reports — GitHub Issues
• Feature Suggestions — GitHub Discussions (Ideas) or Feature Request Issue
• Questions & Help — If you have any questions about using OpenCodeReview, feel free to ask in GitHub Discussions

License

By contributing to OpenCodeReview, you agree that your contributions will be licensed under the Apache License 2.0.