From d0a24c4de32abe9fa530babcb63b9841762f702b Mon Sep 17 00:00:00 2001 From: Lei Zhang Date: Sat, 30 May 2026 14:22:50 +0800 Subject: [PATCH] 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. --- .github/ISSUE_TEMPLATE/bug_report.yml | 100 ++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/docs_report.yml | 48 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 61 ++++++ .github/pull_request_template.md | 33 ++++ CONTRIBUTING.md | 219 +++++++++++++++++++++ CONTRIBUTING.zh-CN.md | 219 +++++++++++++++++++++ 7 files changed, 688 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/docs_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.zh-CN.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c413a55 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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). diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0785ee8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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. diff --git a/.github/ISSUE_TEMPLATE/docs_report.yml b/.github/ISSUE_TEMPLATE/docs_report.yml new file mode 100644 index 0000000..92d3be9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_report.yml @@ -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..." diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..2d39813 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6345b25 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,33 @@ +## Description + + + +## 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? + + + + +- [ ] `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 + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..11ea5a6 --- /dev/null +++ b/CONTRIBUTING.md @@ -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//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: + +``` +(): + +[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). diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000..1f74621 --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -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/) 规范： + +``` +(): <简短描述> + +[可选的详细说明] +``` + +示例： + +``` +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) 进行许可。