alibaba__open-code-review/CONTRIBUTING.zh-CN.md

贡献指南

感谢你对 OpenCodeReview 的关注！无论是修复拼写错误、报告 Bug，还是实现新功能，每一份贡献都很有价值。

English version | 日本語版 | 한국어 | Русский

行为准则

参与本项目即表示你同意维护一个尊重和包容的环境。请在所有交流中保持友善和建设性。

贡献方式

除了写代码，还有很多方式可以参与贡献：

• 报告 Bug — 发现问题？请提交 issue 并附上复现步骤。
• 建议功能 — 有改进想法？可以在 GitHub Discussions 中发起讨论，或直接提交一个 Feature Request issue。
• 改进文档 — 修复错别字、完善说明或补充示例。也可以提交一个 Documentation Issue 来报告文档问题。
• 审查 PR — 帮助我们审查其他贡献者的代码。
• 编写代码 — 修复 Bug、添加功能或提升性能。

快速开始

前置条件

• Go 1.25+
• Git
• Make

环境搭建

# 1. 在 GitHub 上 Fork 本仓库

# 2. 克隆你的 Fork
git clone https://github.com/<你的用户名>/open-code-review.git
cd open-code-review

# 3. 添加上游远端（用于同步主仓库的最新变更）
git remote add upstream https://github.com/alibaba/open-code-review.git

# 4. 构建项目
make build

# 5. 运行测试
make test

如果一切通过，就可以开始贡献了。

注意： upstream 远端对贡献者是只读的，仅用于拉取主仓库的最新更新。你不能直接向 upstream 推送代码，所有贡献必须推送到你的 fork（origin），然后通过 Pull Request 提交。

开发工作流

分支管理

从 main 创建功能分支：

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

使用前缀标明变更类型：

前缀	用途
feat/	新功能
fix/	Bug 修复
docs/	仅文档变更
refactor/	代码重构（无行为变化）
test/	添加或更新测试
chore/	构建、CI 或工具链变更

提交信息

遵循 Conventional Commits 规范：

<type>(<scope>): <简短描述>

[可选的详细说明]

示例：

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

许可证头

每个源文件（.go、.sh、.js、.mjs、.ts、.tsx）都必须包含 SPDX 许可证头。创建新文件后请运行：

make license-add

此命令会自动添加所需的许可证头。CI 会拒绝缺少许可证头的 PR。

代码质量

提交前请确保通过以下检查：

# 格式化、静态检查、验证许可证头
make check

# 带竞态检测运行测试
make test

# 构建成功
make build

项目结构

├── cmd/opencodereview/   # CLI 入口
├── internal/
│   ├── agent/            # 评审 Agent 逻辑
│   ├── config/           # 配置管理
│   ├── diff/             # Git diff 解析
│   ├── llm/              # LLM API 客户端（Anthropic & OpenAI）
│   ├── model/            # 数据模型
│   ├── session/          # 评审会话管理
│   ├── tool/             # 内置工具（file_read, code_search 等）
│   ├── telemetry/        # OpenTelemetry 集成
│   └── viewer/           # WebUI 会话查看器
├── pages/                # WebUI 前端
├── scripts/              # 构建和安装脚本
└── bin/                  # NPM 包装器

AI 参与辅助开发

使用 AI 协助开发完全没有问题，如果它能让贡献变得更轻松，我们也很高兴。我们无法接受的是：模型生成的代码未经阅读就直接进入提交，其中的冗余和错误无人清理。这类提交会拖慢评审沟通，也让拉取请求更难推进。

如果 AI 参与了你的开发过程，请遵守下面的规则。

规则:

1. 您必须在初始问题或拉取请求中披露您使用了 AI/LLM，以及您使用的工具/模型等。
2. 您应当理解 AI 写出的每行代码，了解 AI 做了什么。
3. 当审查者询问某处改动的原因，您需要作出解释，不论这是您写的还是 AI 写的。您对维护者问题和审查意见的回答，其实质内容必须出自您本人的理解；AI/LLM 仅可用于翻译或语言润色，不得用于替您生成回答。
4. 您的 PR 中不应该出现 AI 生成 -> 修复 -> 修复 -> 修复 多次这样的循环，这可能显示您并没有审查 AI 生成的代码，而是在出现问题后再让 AI 自己修复，循环往复。
5. 您必须在主动请求任何成员为您审查之前，先自己审查所有由 AI/LLM 生成的代码、文本等内容。
6. 您不得将提交记录归于 AI/LLM，包括通过“Assisted-by”、“Co-developed-by”或类似的提交尾部。
7. 请勿编写冗长的提交信息，重要的信息应该放在 PR 简介而不是被折叠的提交信息里。
8. 如果您感到不愿或无法做到以上所有事项，请关闭您的问题或拉取请求。

谢谢！

文档贡献

文档是 OpenCodeReview 的重要组成部分。我们欢迎对 README、代码注释、配置示例以及任何面向用户的文本进行改进。

哪些算文档贡献

• 修复错别字、语法错误或失效链接
• 完善表述不清的说明或补充缺失的上下文
• 为命令或配置项添加使用示例
• 更新过时的内容（例如功能变更后的文档同步）
• 翻译或改进中英文文档（README.zh-CN.md、CONTRIBUTING.zh-CN.md）

文档贡献流程

1. 如果你发现问题但暂时不打算自己修复，请提交一个 Documentation Issue。
2. 如果你想直接修复，fork 仓库后修改，提交 PR 时使用 docs/ 分支前缀（例如 docs/fix-config-example）。
3. 纯文档 PR 不需要修改测试，但请确保文中涉及的命令和代码片段准确无误。

文档文件一览

文件	用途
README.md	项目主文档（英文）
README.zh-CN.md	中文翻译
CONTRIBUTING.md	贡献指南（英文）
CONTRIBUTING.zh-CN.md	贡献指南（中文）

提交变更

提交 Issue

在进行重大修改之前，请先开一个 issue 讨论方案。这可以避免重复劳动，并确保你的贡献与项目方向一致。

报告 Bug 时请包含：

1. OpenCodeReview 版本（ocr version）
2. 操作系统和架构
3. 复现步骤
4. 预期行为与实际行为
5. 相关日志或错误信息

Pull Request 流程

1. 保持 PR 聚焦 — 每个 PR 只包含一个逻辑变更。多个独立改动请分别提交 PR。
2. 编写测试 — 为行为变更添加或更新测试。
3. 更新文档 — 如果变更影响用户侧行为，请同步更新相关文档。
4. 签署 CLA — 所有贡献者需在 PR 合并前签署贡献者许可协议（详见下方）。
5. 填写 PR 模板 — 描述你的改动是什么以及为什么这样做。

PR 标题格式

使用与 commit message 相同的 Conventional Commits 格式：

feat(agent): add support for custom tool definitions

审查流程

• 维护者通常会在几个工作日内审查你的 PR。
• 我们可能会要求修改——这很正常，是协作而非对立。
• 一旦批准，维护者会合并你的 PR。

让你的 PR 更快被处理

希望你的 PR 尽快被审查和合并？以下做法会有所帮助：

• 尽早签署 CLA — 很多首次贡献者因为忽略了 CLA bot 的评论而被卡住。一旦 bot 提示，请立即签署贡献者许可协议——未签署 CLA 的 PR 无法被合并。
• 确保所有 CI 检查通过 — CI 未通过的 PR 不会被审查。推送前请在本地运行 make test 和 make build，提前发现问题。
• 保持改动聚焦且精简 — 只做一件事的 PR 远比混杂无关改动的 PR 更容易审查。越小的 PR 审查越快，需要多轮修改的可能性也越低。
• 撰写清晰、准确的描述 — 说明改了什么以及为什么。描述必须与实际 diff 一致——两者不符会让审查者失去信任。如果开发过程中范围发生了变化，请在请求审查前更新描述。
• 为行为变更编写测试 — 没有测试的新功能或缺陷修复会引发疑问。测试能证明正确性，并帮助审查者理解预期行为。
• 遵循现有代码风格 — 与周围代码的风格、命名规范和架构保持一致。一致性降低审查者的认知负担，也避免纯风格相关的评论。
• 及时回应反馈 — 审查者提出修改意见后，请尽快处理以缩短审查周期。如果有不同意见，请解释你的理由而不是忽略评论。

贡献者许可协议（CLA）

我们要求所有贡献者在合并代码前签署阿里巴巴开源贡献者许可协议（CLA）。这确保项目可以在其许可条款下合法分发。

当你首次提交 PR 时，CLA bot 会自动发布评论并附上签署说明。只需点击链接进行电子签署即可，整个过程只需一分钟。

新手推荐

第一次参与？可以关注以下标签的 issue：

• good first issue — 小型、范围明确的任务，适合快速上手。
• help wanted — 我们希望得到社区帮助的问题。

适合入手的方向：

• 改善错误信息和 CLI 输出
• 为未覆盖的代码路径编写测试
• 文档改进

社区

• Bug 报告 — GitHub Issues
• 功能建议 — GitHub Discussions (Ideas) 或 Feature Request Issue
• 使用疑问与帮助 — 对 OpenCodeReview 的使用有任何疑问，欢迎在 GitHub Discussions 中提问交流

许可证

向 OpenCodeReview 贡献代码即表示你同意你的贡献将以 Apache License 2.0 进行许可。