chore: add comprehensive contributing guide

[FutureUnreal]

变更说明

关联 Issue / 需求

自测方式

• 后端：cd backend && uv run uvicorn app.main:app --reload --port 8090
• 前端：cd frontend && pnpm --filter @whalewhisper/web dev

风险 & 回滚

Checklist

• 已保证改动聚焦（不混杂无关重构）
• 已更新相关文档（如 README / 配置示例）
• 未提交任何密钥/个人信息
• CI（PR Checks）通过

📝 PR 说明（Codex 自动生成）

• 变更概览：新增 CONTRIBUTING.md，提供中英双语贡献指南，覆盖行为准则、开发环境搭建（backend/frontend）、分支/提交规范、代码风格、测试、PR/Issue 流程等。主要用于统一协作规范、降低新贡献者上手成本（不涉及运行时代码改动）。
• 影响范围：docs
• 如何验证：
  1. 在 GitHub PR 预览中打开 CONTRIBUTING.md，确认目录/锚点跳转与中英导航正常、代码块渲染无异常。
  2. 快速核对文档中引用的关键路径与命令是否与仓库一致（如 backend/config/engines.yaml、backend/app/main.py、pnpm --filter @whalewhisper/web dev 等）。
• 风险点：文档中克隆地址使用 datawhalechina/WhaleWhisper.git（与当前仓库 URL 命名不一致，可能依赖 GitHub 重定向）；部分示例命令/配置可能随项目演进而过期，需要后续维护同步。

[qodo-code-review]

Review Summary by Qodo

Add comprehensive bilingual contributing guide

📝 Documentation

Walkthroughs

Description

• Add comprehensive bilingual contributing guide (Chinese/English)
• Document development setup, branch naming, and commit conventions
• Provide code style guidelines for Python backend and TypeScript/Vue frontend
• Include testing procedures, PR workflow, and issue reporting templates

Diagram

flowchart LR
  A["Contributing Guide"] --> B["Chinese Section"]
  A --> C["English Section"]
  B --> D["Setup Instructions"]
  B --> E["Code Style & Testing"]
  B --> F["PR & Issue Process"]
  C --> D
  C --> E
  C --> F

Loading

File Changes

1. CONTRIBUTING.md 📝 Documentation +659/-0

Comprehensive bilingual contributing guide with setup and standards

• Created new comprehensive contributing guide with bilingual support (Chinese and English)
• Documented project introduction, code of conduct, and quick start setup for backend/frontend
• Specified branch naming conventions, commit message format following Conventional Commits
• Provided detailed code style guidelines for Python (PEP 8, async-first, type hints) and
 TypeScript/Vue (2-space indent, Composition API)
• Included testing procedures for backend and frontend with specific commands
• Outlined PR submission process, merge strategy, and issue reporting templates with examples

CONTRIBUTING.md

---

[greptile-apps]

Greptile Overview

Greptile Summary

Added comprehensive bilingual (Chinese/English) contributing guide covering the complete contribution workflow. The document provides clear guidance on setup, branch naming, commit conventions, code style, testing, and PR process.

Key additions:

• Detailed onboarding with backend/frontend setup instructions
• Branch naming conventions (feature/, fix/, hotfix/, chore/)
• Conventional Commits format with examples
• Code style guidelines for Python (PEP 8) and TypeScript/Vue
• Testing procedures for both backend and frontend
• PR workflow emphasizing the dev branch as the base
• Issue reporting templates and guidelines

Minor issues found:

• References to backend/tests/ directory which doesn't exist yet - should clarify this is for future use

Confidence Score: 4/5

• This PR is safe to merge with minimal risk - it's a documentation-only change
• The PR adds a comprehensive contributing guide which is well-structured and thorough. Only minor issue is a reference to a non-existent tests directory, which doesn't affect functionality but should be clarified to avoid confusion for contributors.
• No files require special attention - the issue with the tests directory reference is minor and easily addressed

Important Files Changed

Filename	Overview
CONTRIBUTING.md	Added comprehensive bilingual contributing guide with detailed workflow, conventions, and testing procedures

Sequence Diagram

sequenceDiagram
    participant C as Contributor
    participant GH as GitHub
    participant CI as CI Pipeline
    participant M as Maintainer
    participant Dev as dev branch
    participant Main as main branch

    Note over C,Main: Contribution Workflow

    C->>GH: Fork repository
    C->>C: git checkout dev
    C->>C: git pull origin dev
    C->>C: git checkout -b feature/new-feature
    
    C->>C: Make code changes
    C->>C: Run local tests<br/>(compileall, typecheck, build)
    
    C->>GH: git push origin feature/new-feature
    C->>GH: Create PR targeting dev branch
    
    GH->>CI: Trigger PR checks
    CI->>CI: Run backend checks
    CI->>CI: Run frontend checks
    CI->>GH: Report CI status
    
    GH->>M: Notify maintainer
    M->>GH: Review PR (within 2 business days)
    
    alt Changes requested
        M->>C: Request changes
        C->>C: Make updates
        C->>GH: Push to same branch
        GH->>CI: Re-run checks
    end
    
    alt PR approved and CI passes
        M->>Dev: Squash and merge PR
        Note over Dev: PR merged to dev branch
        
        Note over Main: Periodic releases
        M->>Main: Release merge from dev
    end

Loading

[greptile-apps]

_{1 file reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. API key in example config 📘 Rule violation ⛨ Security

Description

• The contributing guide includes a configuration example that places an api_key directly in
  backend/config/engines.yaml.
• Even as a placeholder, this pattern can lead contributors to store real API keys in a tracked file
  and accidentally commit secrets.
• This conflicts with the requirement to handle sensitive data securely and avoid exposure of
  tokens/keys in project artifacts.

Code

CONTRIBUTING.md[R80-89]

+编辑 `backend/config/engines.yaml` 配置 LLM/ASR/TTS 提供商：
+
+```yaml
+llm:
+  default: openai
+  providers:
+    openai:
+      api_key: "your-api-key"
+      model: "gpt-4"
+```

Evidence

PR Compliance ID 6 requires secure handling of sensitive data (including tokens/keys) and flags
exposure of such data as failure criteria. The new CONTRIBUTING.md shows an api_key field in a
config file example, which may encourage placing real secrets in a repository file.

Rule 6: Generic: Security-First Input Validation and Data Handling
CONTRIBUTING.md[80-89]
CONTRIBUTING.md[399-408]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CONTRIBUTING.md` currently shows an `api_key` being placed directly into `backend/config/engines.yaml`. Even as a placeholder, this can normalize storing real secrets in a tracked config file and increase the risk of accidental secret commits.

## Issue Context
The compliance checklist requires sensitive data (tokens/keys) to be handled securely and not exposed. The contributing guide is a key source of truth for contributor behavior, so it should steer contributors toward safer secret handling patterns.

## Fix Focus Areas
- CONTRIBUTING.md[78-90]
- CONTRIBUTING.md[397-409]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. uv invocation inconsistent 🐞 Bug ⛯ Reliability

Description

• CONTRIBUTING.md recommends creating/installing with uv, but then starts the server using plain
  uvicorn ... without uv run or venv activation.
• On many systems, this will run a global uvicorn (or fail to find it), leading to confusing
  import/dependency errors.
• The repository README demonstrates the correct pattern (uv run uvicorn ...).

Code

CONTRIBUTING.md[R55-96]

+#### 后端设置
+
+```bash
+cd backend
+
+# 方式一：使用 uv（推荐）
+uv venv
+uv pip install -e ".[dev]"
+
+# 方式二：使用传统 venv
+python -m venv .venv
+.venv\Scripts\activate  # Windows
+# source .venv/bin/activate  # Linux/Mac
+pip install -e ".[dev]"
+```
+
+#### 前端设置
+
+```bash
+cd frontend
+pnpm install
+```
+
+#### 配置环境
+
+编辑 `backend/config/engines.yaml` 配置 LLM/ASR/TTS 提供商：
+
+```yaml
+llm:
+  default: openai
+  providers:
+    openai:
+      api_key: "your-api-key"
+      model: "gpt-4"
+```
+
+#### 启动开发服务器
+
+```bash
+# 后端（在 backend/ 目录）
+uvicorn app.main:app --reload --port 8090
+

Evidence

CONTRIBUTING.md’s uv path does not show any activation step, yet uses uvicorn directly. The
repo’s README shows uv run uvicorn ..., indicating the intended/working invocation when using `uv
venv + uv pip install`.

CONTRIBUTING.md[55-63]
CONTRIBUTING.md[91-96]
README.md[83-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide’s recommended `uv` setup path is followed by a server start command that doesn’t use `uv run` or venv activation, which can cause the wrong interpreter/environment to be used.

## Issue Context
The repo README uses `uv run uvicorn ...` for the `uv` workflow.

## Fix Focus Areas
- CONTRIBUTING.md[55-63]
- CONTRIBUTING.md[91-99]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Python version unclear 🐞 Bug ✓ Correctness

Description

• CONTRIBUTING.md suggests “Python 3.8+” for type hints, but the backend package explicitly requires
  Python >=3.10.
• This ambiguity can cause contributors to try 3.8/3.9 first and hit avoidable installation
  failures.
• The included example type hint syntax (dict[str, str]) also implies 3.9+, further conflicting
  with the stated 3.8+ guidance.

Code

CONTRIBUTING.md[R165-180]

+- 遵循 PEP 8 规范
+- 使用 4 空格缩进
+- 类型注解：优先使用 Python 3.8+ 类型提示
+- 异步优先：FastAPI 路由使用 `async def`
+- 配置驱动：使用 YAML 配置文件而非硬编码
+
+**示例：**
+```python
+from typing import Optional
+from fastapi import APIRouter
+
+router = APIRouter()
+
+@router.get("/health")
+async def health_check() -> dict[str, str]:
+    return {"status": "ok"}

Evidence

CONTRIBUTING.md states 3.8+ type-hint guidance while the backend’s pyproject requires >=3.10. CI
also runs on Python 3.11, reinforcing that contributors should target 3.10+ for backend development.

CONTRIBUTING.md[165-180]
backend/pyproject.toml[1-6]
.github/workflows/pr-check.yml[32-37]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
CONTRIBUTING.md implies Python 3.8+ is acceptable (at least for backend style guidance), but the backend package requires Python >=3.10. This mismatch can mislead contributors during setup.

## Issue Context
`backend/pyproject.toml` is the authoritative source for supported Python versions.

## Fix Focus Areas
- CONTRIBUTING.md[165-180]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[github-actions]

🤖 Codex PR Review

PR Summary

• Adds a new bilingual CONTRIBUTING.md with contribution workflow, branch/commit conventions, and dev setup instructions.
• Scope: +659 / -0, 1 file changed.

Key Risks

• “Getting started” steps contain repo URLs, config examples, and commands that don’t match the current repo layout/config → high chance of contributor confusion and failed setup.
• YAML example suggests putting API keys directly in config, which increases the chance of accidental secret leakage.

Findings

• [High] [DOCS] CONTRIBUTING.md:51 — Clone + GitHub links point to a different repo slug

  • Evidence: git clone https://github.com/datawhalechina/WhaleWhisper.git
  • Why it matters: This repo is datawhalechina/whale-whisper; the current URLs (also used for Issues/Discussions) may 404 or send contributors to the wrong place.
  • Suggested fix:

    - git clone https://github.com/datawhalechina/WhaleWhisper.git
    - cd WhaleWhisper
    + git clone https://github.com/datawhalechina/whale-whisper.git
    + cd whale-whisper

    - https://github.com/datawhalechina/WhaleWhisper/issues
    - https://github.com/datawhalechina/WhaleWhisper/discussions
    + https://github.com/datawhalechina/whale-whisper/issues
    + https://github.com/datawhalechina/whale-whisper/discussions

• [High] [SECURITY] CONTRIBUTING.md:80 — engines.yaml example doesn’t match actual schema and encourages inline API keys

  • Evidence:

    llm:
      default: openai
      providers:
        openai:
          api_key: "your-api-key"

  • Why it matters: The repo’s backend/config/engines.yaml uses an engines: list and api_key_env (env-var based). The current example is likely to break setup and increases risk of committing secrets.
  • Suggested fix (update both CN+EN sections):

    - llm:
    -   default: openai
    -   providers:
    -     openai:
    -       api_key: "your-api-key"
    -       model: "gpt-4"
    + llm:
    +   default: openai
    +   engines:
    +     - id: openai
    +       type: openai_compat
    +       base_url: https://api.openai.com/v1
    +       model: gpt-4o-mini
    +       api_key_env: OPENAI_API_KEY

    And add a one-liner warning like: “Do not commit secrets; set OPENAI_API_KEY in your environment.”

• [Medium] [DOCS] CONTRIBUTING.md:95 — uv path likely fails without uv run / venv activation

  • Evidence: uv venv … then uvicorn app.main:app --reload --port 8090
  • Why it matters: After uv venv + uv pip install, uvicorn may not be on PATH unless you activate .venv or use uv run, so the “recommended” path may not work out-of-the-box.
  • Suggested fix:

    - uvicorn app.main:app --reload --port 8090
    + uv run uvicorn app.main:app --reload --port 8090

    (or explicitly instruct activating .venv on Linux/Mac instead of leaving it commented out)

• [Medium] [DOCS] CONTRIBUTING.md:235 — Frontend guidance references non-existent script/path

  • Evidence: pnpm run typecheck and frontend/packages/shared
  • Why it matters: frontend/package.json and frontend/apps/web/package.json don’t define a typecheck script, and there is no frontend/packages/shared directory; contributors following the guide will hit dead ends.
  • Suggested fix:

    - # 类型检查
    - pnpm run typecheck
    -
    - # 构建测试
    - pnpm --filter @whalewhisper/web build
    + # 构建测试（当前未配置独立的 typecheck 命令）
    + pnpm --filter @whalewhisper/web build

    - 工具函数：放在 `frontend/packages/shared` 或相应模块的 `utils/` 目录
    + 工具函数：优先放在 `frontend/packages/*/src/`（如 `frontend/packages/app-core/src/`），或相应模块的 `utils/` 目录