CONTRIBUTING.md

🤝 贡献指南 | CONTRIBUTING

🇺🇸 English version is provided after the Chinese section. Scroll to English Contributing Guide for the translation.

🔁 语言导航 | Language Navigation

• 🇨🇳 中文贡献指南
• 🇺🇸 English Contributing Guide

🇨🇳 中文贡献指南

📚 中文目录

• 1. 介绍 Introduction
• 2. 行为准则 Code of Conduct
• 3. 快速开始 Getting Started
• 4. 如何贡献 How to Contribute
• 5. 分支命名 Branch Naming
• 6. 提交格式 Commit Format
• 7. 代码风格 Code Style
• 8. 测试 Testing
• 9. PR 流程 PR Process
• 10. 问题反馈 Issue Reporting

1. 介绍 Introduction

Claude Code Hub 是一个面向团队的 AI API 代理平台，支持统一管理多家供应商、智能分流和现代化运维工具。本文档说明如何按照项目既定流程参与贡献，帮助你提交高质量的 Pull Request（PR）。

2. 行为准则 Code of Conduct

• 遵循友好、尊重和包容的沟通方式，参考 Contributor Covenant 2.1 精神。
• 尊重不同背景与观点，不得发布任何歧视、骚扰或攻击性言论。
• 讨论基于事实和数据，避免进行人身攻击。
• 社区交流渠道：GitHub Issues/Discussions 与 Telegram 群（见 README），通常会在 2 个工作日内回复。

3. 快速开始 Getting Started

1. 克隆仓库并安装依赖：

   git clone https://github.com/ding113/claude-code-hub.git
   cd claude-code-hub
   bun install

2. 复制并配置环境变量：

   cp .env.example .env

3. 本地启动：

   bun run dev

4. 需要容器化体验可参考 README.md 与 .github/CI_CD_SETUP.md 中的 Docker 流程。

4. 如何贡献 How to Contribute

⚠️ 重要：所有 PR 必须以 dev 分支为目标。
📌 注意：main 仅用于发布，禁止直接合并或推送。

1. 在开始前同步最新 dev：

   git checkout dev
   git pull origin dev

2. 根据需求创建功能或修复分支：

   git checkout -b feature/provider-weight-ui

3. 开发过程中保持变更粒度小，提交前运行必要的检查（见 测试）。
4. 提交并推送：

   git add .
   git commit -m "feat: add provider weight ui"
   git push origin feature/provider-weight-ui

5. 在 GitHub 上创建指向 dev 的 PR，详细填写描述、截图与验证步骤。更多工作流细节请阅读 .github/CI_CD_SETUP.md。

5. 分支命名 Branch Naming

• feature/<short-description>：新功能或较大改动（例：feature/audit-log-export）
• fix/<issue-id-or-scope>：缺陷修复（例：fix/redis-timeout）
• hotfix/<scope>：紧急线上修复，仍需先合入 dev
• chore/<scope>：依赖更新、文档、脚本等

6. 提交格式 Commit Format

遵循 Conventional Commits，使用英文动词简述改动。常用类型：

类型	用途
feat	新功能或重大增强
fix	缺陷修复
chore	构建、配置或文档
refactor	重构，不引入新功能
test	新增或更新测试

示例：feat: add provider priority routing

7. 代码风格 Code Style

• TypeScript + React 组件遵守 2 空格缩进、双引号和尾随逗号（Biome 默认配置）。
• Tailwind CSS 样式与 JSX 同行，沿用 README 中的 emoji 样式和语气。
• 工具函数保持单一职责，避免重复代码（DRY）。
• 新增文件前参考 src/ 下相同模块的实现，保持命名一致。

8. 测试 Testing

在每次提交前务必运行：

bun run lint
bun run typecheck
# 如果更改影响运行逻辑，执行端到端验证或 bun run test

i18n 变更（翻译质量/抽查）

如果 PR 涉及 i18n 文案（尤其是 settings / dashboard / myUsage），请遵循：

• 规则说明：docs/i18n-translation-quality.md
• PR Checklist：docs/i18n-pr-checklist.md

CI 会在 PR 上运行 Docker Build Test（见 .github/CI_CD_SETUP.md）。如需验证容器构建，可本地执行：

docker compose build

9. PR 流程 PR Process

⚠️ 重要：PR 的 base 分支必须是 dev，CI 通过后方可合并。
📌 注意：若 PR 过期，请先 git fetch && git rebase origin/dev，保持与受保护分支同步。

1. 创建 PR 时附上变更摘要、测试截图或日志。
2. 检查列表：
   • 目标分支为 dev
   • 所有状态检查（Docker Build Test）已通过
   • 与 main 无直接冲突
   • 引用相关 Issue 或任务（如有）
3. Reviewer 会在 2 个工作日内反馈；需要改动时请直接推送到同一分支。
4. 合并策略遵循 “Squash and merge”，保持干净的提交历史。

10. 问题反馈 Issue Reporting

• 在 GitHub Issues 中创建问题，选择合适的标签（bug/feature/question）。
• 描述内容包括：环境信息、复现步骤、预期结果与实际结果、日志或截图。
• 紧急情况可在 Issues 评论中 @Maintainer 或加入 Telegram 群同步说明。
• 提交 Issue 前可搜索是否已有类似讨论，避免重复。

---

🇺🇸 English Contributing Guide

📚 English Table of Contents

• 1. Introduction
• 2. Code of Conduct
• 3. Getting Started
• 4. How to Contribute
• 5. Branch Naming
• 6. Commit Format
• 7. Code Style
• 8. Testing
• 9. PR Process
• 10. Issue Reporting

1. Introduction

Claude Code Hub centralizes multiple AI providers with smart routing, tenant controls, and observability. This document explains how to deliver high-quality Pull Requests (PRs) that align with the project roadmap.

2. Code of Conduct

• Communicate with respect, empathy, and patience—follow the spirit of Contributor Covenant 2.1.
• Absolutely no harassment, discrimination, or personal attacks.
• Base discussions on facts and data; document trade-offs clearly.
• Primary channels: GitHub Issues/Discussions and the Telegram group listed in README.md. Expect responses within two business days.

3. Getting Started

1. Clone and install dependencies:

   git clone https://github.com/ding113/claude-code-hub.git
   cd claude-code-hub
   bun install

2. Copy environment variables and configure secrets:

   cp .env.example .env

3. Launch the dev server:

   bun run dev

4. For Docker-based flows, review README.md and .github/CI_CD_SETUP.md.

4. How to Contribute

⚠️ Important: Every PR must target the dev branch.
📌 Notice: main is release-only; never push or merge into it directly.

1. Sync the latest dev branch before coding:

   git checkout dev
   git pull origin dev
   git checkout -b feature/provider-weight-ui

2. Keep changes scoped and document reasoning inside commits or PR descriptions.
3. Run the checks listed in Testing before pushing.
4. Push the branch and open a PR against dev. Reference .github/CI_CD_SETUP.md for branch protection and CI expectations.

5. Branch Naming

• feature/<short-description> — new capabilities or UI work
• fix/<issue-id-or-scope> — bug fixes
• hotfix/<scope> — urgent production fixes (merge into dev via PR)
• chore/<scope> — docs, tooling, dependency bumps

6. Commit Format

Follow Conventional Commits with concise English summaries:

Type	Purpose
feat	Introduce a feature or enhancement
fix	Resolve a bug
chore	Tooling, docs, or maintenance
refactor	Internal refactors without behavior changes
test	Add or adjust tests

Example: fix: handle redis timeout retry

7. Code Style

• Respect the shared Biome config (2-space indent, double quotes, trailing commas).
• Tailwind classes stay close to the JSX they style, mirroring patterns in src/app.
• Keep utilities single-purpose and reuse helpers from src/lib or src/actions when possible.
• Match the conversational tone (emojis + concise explanations) already used in README.md.

8. Testing

Always verify locally before requesting a review:

bun run lint
bun run typecheck
# Run bun run test or relevant scripts when logic changes
docker compose build   # optional, mirrors CI Docker Build Test

GitHub Actions runs Docker Build Test on every PR to dev and main; see .github/CI_CD_SETUP.md for the full matrix.

9. PR Process

⚠️ Important: Set the PR base to dev, ensure CI is green before merging.
📌 Notice: Rebase onto origin/dev if the branch falls behind protected rules.

1. Fill out the PR template with context, screenshots/logs, and testing notes.
2. Confirm the checklist:
   • Base branch is dev
   • Docker Build Test (and other required checks) succeed
   • Conflicts resolved and branch up to date
   • Linked Issues or Discussions when applicable
3. Maintainers aim to respond within two business days. Continue pushing to the same branch for follow-up changes.
4. Merges use “Squash and merge” to keep history tidy.

10. Issue Reporting

• File Issues with clear titles, labels, reproduction steps, expected vs. actual behavior, and logs or screenshots.
• Include environment details (OS, Docker/Node versions, provider configuration).
• For urgent incidents, leave a comment tagging maintainers or post in the Telegram group.
• Search existing Issues/Discussions to prevent duplicates before creating a new report.

---

感谢你为 Claude Code Hub 做出的贡献！Thanks for helping improve Claude Code Hub!