Add issue and PR templates with bilingual contributing guide (#9)

* docs: add GitHub issue and PR templates

Add structured issue templates for bug reports, feature requests, and docs reports with YAML forms. Include a pull request template with checklist for contribution quality.

* docs: add bilingual contributing guide (EN & zh-CN)

Provide detailed contribution guidelines covering development setup, coding standards, commit conventions, PR workflow, and community conduct in both English and Chinese.
This commit is contained in:
Lei Zhang 2026-05-30 14:22:50 +08:00 committed by GitHub
parent 2d7697a7fe
commit d0a24c4de3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 688 additions and 0 deletions

100
.github/ISSUE_TEMPLATE/bug_report.yml vendored Normal file
View file

@ -0,0 +1,100 @@
name: Bug Report
description: Report a bug encountered while using OpenCodeReview
labels: ["bug"]
type: Bug
body:
- type: markdown
attributes:
value: |
Thank you for taking the time to report a bug! Please fill out the form below so we can investigate effectively.
Before opening a new issue, please [search existing issues](https://github.com/alibaba/open-code-review/issues) to avoid duplicates.
- type: input
id: version
attributes:
label: OpenCodeReview Version
description: Run `ocr version` and paste the output here.
placeholder: "v0.1.0 (commit: abc1234, built: 2026-05-01T00:00:00Z)"
validations:
required: true
- type: dropdown
id: os
attributes:
label: Operating System
options:
- macOS (Apple Silicon)
- macOS (Intel)
- Linux (x86_64)
- Linux (ARM64)
- Windows
- Other
validations:
required: true
- type: dropdown
id: install-method
attributes:
label: Installation Method
options:
- npm (global)
- GitHub Release binary
- Built from source
validations:
required: true
- type: dropdown
id: llm-provider
attributes:
label: LLM Provider
description: Which LLM API are you using?
options:
- Anthropic (Claude)
- OpenAI
- Azure OpenAI
- Other OpenAI-compatible endpoint
validations:
required: true
- type: textarea
id: description
attributes:
label: Bug Description
description: A clear and concise description of what the bug is.
placeholder: "When I run `ocr review`, the CLI crashes with..."
validations:
required: true
- type: textarea
id: reproduce
attributes:
label: Steps to Reproduce
description: Step-by-step instructions to reproduce the issue.
placeholder: |
1. Configure LLM with `ocr config set ...`
2. Run `ocr review --from main --to feature`
3. Observe error message...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
description: What did you expect to happen?
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs / Error Output
description: Paste any relevant error messages or logs. Please redact any API keys or sensitive information.
render: shell
- type: textarea
id: additional
attributes:
label: Additional Context
description: Any other information that might help us investigate (e.g., custom review rules, specific file types, network environment).

8
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: "\U0001F4AC Questions & Help"
url: https://github.com/alibaba/open-code-review/discussions/categories/q-a
about: Ask questions or get help with configuration in Discussions.
- name: "\U0001F4A1 Ideas & Feature Discussions"
url: https://github.com/alibaba/open-code-review/discussions/categories/ideas
about: Discuss feature ideas before opening a formal request.

48
.github/ISSUE_TEMPLATE/docs_report.yml vendored Normal file
View file

@ -0,0 +1,48 @@
name: Documentation Issue
description: Report an issue with documentation or suggest improvements
labels: ["documentation"]
type: Docs
body:
- type: markdown
attributes:
value: |
Thank you for helping us improve our documentation! Please describe the issue or suggestion below.
- type: dropdown
id: type
attributes:
label: Issue Type
options:
- Incorrect information
- Missing documentation
- Unclear / confusing explanation
- Typo or grammar error
- Outdated content
- Other
validations:
required: true
- type: input
id: location
attributes:
label: Document Location
description: Which file or section is affected? Provide a URL or file path if possible.
placeholder: "e.g., README.md > Configuration Reference, or https://github.com/alibaba/open-code-review#review-rules"
validations:
required: true
- type: textarea
id: description
attributes:
label: Description
description: Describe what's wrong or what could be improved.
placeholder: "The configuration example for Anthropic is missing the `llm.use_anthropic` field..."
validations:
required: true
- type: textarea
id: suggestion
attributes:
label: Suggested Change
description: If you have a specific suggestion for how to fix or improve it, please describe it here.
placeholder: "It would be helpful to add an example showing..."

View file

@ -0,0 +1,61 @@
name: Feature Request
description: Suggest a new feature or enhancement for OpenCodeReview
labels: ["enhancement"]
type: Feature
body:
- type: markdown
attributes:
value: |
Thank you for suggesting a feature! Please describe your idea clearly so we can evaluate it.
For questions or open-ended discussions, please use [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions) instead.
- type: textarea
id: problem
attributes:
label: Problem Statement
description: What problem does this feature solve? Is it related to a frustration you've experienced?
placeholder: "I'm always frustrated when..."
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed Solution
description: Describe the solution you'd like. How should it work from a user's perspective?
placeholder: "I'd like to be able to run `ocr review --xxx` which would..."
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives Considered
description: Have you considered any alternative solutions or workarounds?
- type: dropdown
id: area
attributes:
label: Affected Area
description: Which part of the project does this feature relate to?
multiple: true
options:
- CLI / Commands
- Review Agent / LLM interaction
- Review Rules
- Built-in Tools (file_read, code_search, etc.)
- Output / Formatting
- Configuration
- Telemetry / Observability
- WebUI Viewer
- Documentation
- Other
validations:
required: true
- type: textarea
id: additional
attributes:
label: Additional Context
description: Any other context, screenshots, or references that help explain your feature request.

33
.github/pull_request_template.md vendored Normal file
View file

@ -0,0 +1,33 @@
## Description
<!-- What does this PR do? Why is this change needed? -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Refactoring (no functional changes)
- [ ] Documentation update
- [ ] CI / Build / Tooling
## How Has This Been Tested?
<!-- Describe the tests you ran to verify your changes. -->
<!-- Include relevant details about your test configuration. -->
- [ ] `make test` passes locally
- [ ] Manual testing (describe below)
## Checklist
- [ ] My code follows the project's coding style (`go fmt`, `go vet`)
- [ ] I have performed a self-review of my code
- [ ] I have added tests that prove my fix is effective or my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the documentation accordingly (if applicable)
- [ ] I have signed the CLA
## Related Issues
<!-- Link related issues below. Use "closes #123" to auto-close on merge. -->

219
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,219 @@
# 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.
[简体中文版](CONTRIBUTING.zh-CN.md)
## 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](https://github.com/alibaba/open-code-review/discussions/categories/ideas) or open a [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml) issue.
- **Improve documentation** — Fix typos, clarify explanations, or add examples. You can also open a [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml) 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+](https://go.dev/dl/)
- [Git](https://git-scm.com/)
- [Make](https://www.gnu.org/software/make/)
### Setup
```bash
# 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 contributions must be pushed to your fork (`origin`) and submitted via Pull Request.
## Development Workflow
### Branching
Create a feature branch from `main`:
```bash
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](https://www.conventionalcommits.org/) 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
```
### Code Quality
Before submitting your changes, make sure they pass all checks:
```bash
# Format and lint (Go standard tooling)
go fmt ./...
go vet ./...
# 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
```
## 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 the Chinese documentation (`README.zh-CN.md`, `CONTRIBUTING.zh-CN.md`)
### Documentation Workflow
1. If you spot an issue but don't plan to fix it yourself, open a [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml).
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 |
| `CONTRIBUTING.md` | Contribution guide (English) |
| `CONTRIBUTING.zh-CN.md` | Contribution guide (Chinese) |
| `NPM-README.md` | Description shown on npm registry |
## 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.
## 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`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — Small, well-scoped tasks ideal for getting started.
- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — 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](https://github.com/alibaba/open-code-review/issues)
- **Feature Suggestions** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) or [Feature Request Issue](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml)
- **Questions & Help** — If you have any questions about using OpenCodeReview, feel free to ask in [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions)
## License
By contributing to OpenCodeReview, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).

219
CONTRIBUTING.zh-CN.md Normal file
View file

@ -0,0 +1,219 @@
# 贡献指南
感谢你对 OpenCodeReview 的关注!无论是修复拼写错误、报告 Bug还是实现新功能每一份贡献都很有价值。
[English version](CONTRIBUTING.md)
## 行为准则
参与本项目即表示你同意维护一个尊重和包容的环境。请在所有交流中保持友善和建设性。
## 贡献方式
除了写代码,还有很多方式可以参与贡献:
- **报告 Bug** — 发现问题?请提交 issue 并附上复现步骤。
- **建议功能** — 有改进想法?可以在 [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas) 中发起讨论,或直接提交一个 [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml) issue。
- **改进文档** — 修复错别字、完善说明或补充示例。也可以提交一个 [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml) 来报告文档问题。
- **审查 PR** — 帮助我们审查其他贡献者的代码。
- **编写代码** — 修复 Bug、添加功能或提升性能。
## 快速开始
### 前置条件
- [Go 1.25+](https://go.dev/dl/)
- [Git](https://git-scm.com/)
- [Make](https://www.gnu.org/software/make/)
### 环境搭建
```bash
# 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` 创建功能分支:
```bash
git checkout main
git pull upstream main
git checkout -b feat/your-feature-name
```
使用前缀标明变更类型:
| 前缀 | 用途 |
| ----------- | ---------------------- |
| `feat/` | 新功能 |
| `fix/` | Bug 修复 |
| `docs/` | 仅文档变更 |
| `refactor/` | 代码重构(无行为变化) |
| `test/` | 添加或更新测试 |
| `chore/` | 构建、CI 或工具链变更 |
### 提交信息
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范:
```
<type>(<scope>): <简短描述>
[可选的详细说明]
```
示例:
```
feat(agent): add support for custom tool definitions
fix(llm): handle timeout errors in Anthropic API calls
docs(README): update configuration examples
```
### 代码质量
提交前请确保通过以下检查:
```bash
# 格式化和静态检查
go fmt ./...
go vet ./...
# 带竞态检测运行测试
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 包装器
```
## 文档贡献
文档是 OpenCodeReview 的重要组成部分。我们欢迎对 README、代码注释、配置示例以及任何面向用户的文本进行改进。
### 哪些算文档贡献
- 修复错别字、语法错误或失效链接
- 完善表述不清的说明或补充缺失的上下文
- 为命令或配置项添加使用示例
- 更新过时的内容(例如功能变更后的文档同步)
- 翻译或改进中英文文档(`README.zh-CN.md``CONTRIBUTING.zh-CN.md`
### 文档贡献流程
1. 如果你发现问题但暂时不打算自己修复,请提交一个 [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml)。
2. 如果你想直接修复fork 仓库后修改,提交 PR 时使用 `docs/` 分支前缀(例如 `docs/fix-config-example`)。
3. 纯文档 PR 不需要修改测试,但请确保文中涉及的命令和代码片段准确无误。
### 文档文件一览
| 文件 | 用途 |
| ----------------------- | -------------------- |
| `README.md` | 项目主文档(英文) |
| `README.zh-CN.md` | 中文翻译 |
| `CONTRIBUTING.md` | 贡献指南(英文) |
| `CONTRIBUTING.zh-CN.md` | 贡献指南(中文) |
| `NPM-README.md` | npm 发布页展示的说明 |
## 提交变更
### 提交 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。
## 贡献者许可协议CLA
我们要求所有贡献者在合并代码前签署阿里巴巴开源贡献者许可协议CLA。这确保项目可以在其许可条款下合法分发。
当你首次提交 PR 时CLA bot 会自动发布评论并附上签署说明。只需点击链接进行电子签署即可,整个过程只需一分钟。
## 新手推荐
第一次参与?可以关注以下标签的 issue
- [`good first issue`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — 小型、范围明确的任务,适合快速上手。
- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — 我们希望得到社区帮助的问题。
适合入手的方向:
- 改善错误信息和 CLI 输出
- 为未覆盖的代码路径编写测试
- 文档改进
## 社区
- **Bug 报告** — [GitHub Issues](https://github.com/alibaba/open-code-review/issues)
- **功能建议** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) 或 [Feature Request Issue](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml)
- **使用疑问与帮助** — 对 OpenCodeReview 的使用有任何疑问,欢迎在 [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions) 中提问交流
## 许可证
向 OpenCodeReview 贡献代码即表示你同意你的贡献将以 [Apache License 2.0](LICENSE) 进行许可。