From 50d9d71f90919f74c1a7a7a4e85e4ba0682b7c2b Mon Sep 17 00:00:00 2001 From: lintsinghua Date: Fri, 5 Dec 2025 14:37:07 +0800 Subject: [PATCH] docs: expand contributing guidelines and improve documentation structure - Restructure CONTRIBUTING.md with comprehensive sections including code of conduct, development setup, and PR workflow - Add detailed environment requirements table with version specifications and descriptions - Include step-by-step backend and frontend setup instructions with database initialization - Document code standards for both Python (Ruff, mypy) and TypeScript (Biome) with example commands - Add conventional commits specification with type definitions and practical examples - Provide complete PR process guide from forking through code review - Include project structure diagram for better navigation - Expand DISCLAIMER.md with improved formatting, tables, and clearer responsibility sections - Add AI analysis limitations and technical constraints documentation - Update SECURITY.md with enhanced security guidelines - Refresh backend/env.example and frontend/.env.example with current configuration options - Create new docs/ARCHITECTURE.md for system design documentation - Update docs/CONFIGURATION.md, docs/DEPLOYMENT.md, docs/FAQ.md, and docs/LLM_PROVIDERS.md with improved clarity and structure - Improve overall documentation consistency and user experience across all guides --- CONTRIBUTING.md | 305 ++++++++++++++++++++++++++++++--- DISCLAIMER.md | 265 ++++++++++++++++++++++------ SECURITY.md | 151 ++++++++++++++-- backend/env.example | 130 +++++++++++++- docs/ARCHITECTURE.md | 0 docs/CONFIGURATION.md | 308 +++++++++++++++++++++++++++------ docs/DEPLOYMENT.md | 383 ++++++++++++++++++++++++++++++++++++++--- docs/FAQ.md | 389 ++++++++++++++++++++++++++++++++++++++---- docs/LLM_PROVIDERS.md | 307 +++++++++++++++++++++++++++++---- frontend/.env.example | 75 +++++--- 10 files changed, 2064 insertions(+), 249 deletions(-) create mode 100644 docs/ARCHITECTURE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1487426..f8d8452 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,58 +1,325 @@ # 贡献指南 -我们热烈欢迎所有形式的贡献！无论是提交 issue、创建 PR，还是改进文档，您的每一次贡献对我们都至关重要。 +感谢你对 XCodeReviewer 的关注！我们热烈欢迎所有形式的贡献，无论是提交 Issue、创建 PR，还是改进文档。 -## 开发流程 +## 目录 -1. **Fork** 本项目 -2. 创建您的功能分支 (`git checkout -b feature/AmazingFeature`) -3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`) -4. 推送到分支 (`git push origin feature/AmazingFeature`) -5. 创建一个 **Pull Request** +- [行为准则](#行为准则) +- [如何贡献](#如何贡献) +- [开发环境搭建](#开发环境搭建) +- [代码规范](#代码规范) +- [提交规范](#提交规范) +- [Pull Request 流程](#pull-request-流程) -## 环境要求 +--- -- Node.js 18+ -- Python 3.13+ -- PostgreSQL 15+ -- pnpm 8+ (推荐) 或 npm/yarn +## 行为准则 -## 本地开发 +请在参与项目时保持友善和尊重。我们致力于为每个人提供一个开放、包容的环境。 + +--- + +## 如何贡献 + +### 报告 Bug + +1. 先搜索 [Issues](https://github.com/lintsinghua/XCodeReviewer/issues) 确认问题未被报告 +2. 创建新 Issue，使用 Bug 报告模板 +3. 提供详细信息： + - 操作系统和版本 + - 部署方式（Docker/本地） + - 复现步骤 + - 错误日志或截图 + - 期望行为 vs 实际行为 + +### 提出新功能 + +1. 先搜索 Issues 确认功能未被提出 +2. 创建新 Issue，描述： + - 功能需求背景 + - 期望的实现方式 + - 可能的替代方案 + +### 改进文档 + +文档改进同样重要！你可以： +- 修复文档中的错误 +- 补充缺失的说明 +- 改进文档结构 +- 添加使用示例 + +### 贡献代码 + +1. Fork 本项目 +2. 创建功能分支 +3. 编写代码和测试 +4. 提交 Pull Request + +--- + +## 开发环境搭建 + +### 环境要求 + +| 依赖 | 版本要求 | 说明 | +|------|---------|------| +| Node.js | 18+ | 前端运行环境 | +| Python | 3.13+ | 后端运行环境 | +| PostgreSQL | 15+ | 数据库 | +| pnpm | 8+ | 推荐的前端包管理器 | +| uv | 最新版 | 推荐的 Python 包管理器 | + +### 数据库准备 + +```bash +# 使用 Docker 启动 PostgreSQL（推荐） +docker run -d \ + --name xcodereviewer-db \ + -e POSTGRES_USER=postgres \ + -e POSTGRES_PASSWORD=postgres \ + -e POSTGRES_DB=xcodereviewer \ + -p 5432:5432 \ + postgres:15-alpine +``` ### 后端启动 ```bash +# 1. 进入后端目录 cd backend + +# 2. 创建虚拟环境 uv venv source .venv/bin/activate # Linux/macOS # 或 .venv\Scripts\activate # Windows + +# 3. 安装依赖 uv pip install -e . + +# 4. 配置环境变量 cp env.example .env +# 编辑 .env 文件，配置数据库和 LLM 参数 + +# 5. 初始化数据库 alembic upgrade head + +# 6. 启动后端服务 uvicorn app.main:app --reload --port 8000 ``` ### 前端启动 ```bash +# 1. 进入前端目录 cd frontend + +# 2. 安装依赖 pnpm install + +# 3. 配置环境变量（可选） cp .env.example .env + +# 4. 启动开发服务器 pnpm dev ``` +--- + ## 代码规范 -- 后端使用 Python 类型注解 -- 前端使用 TypeScript -- 提交前请确保代码通过 lint 检查 +### 后端 (Python) -## 问题反馈 +- 使用 Python 3.13+ 类型注解 +- 遵循 PEP 8 代码风格 +- 使用 Ruff 进行代码格式化和检查 +- 使用 mypy 进行类型检查 -如有问题，请通过 [Issues](https://github.com/lintsinghua/XCodeReviewer/issues) 反馈。 +```bash +# 代码格式化 +ruff format app + +# 代码检查 +ruff check app + +# 类型检查 +mypy app +``` + +### 前端 (TypeScript/React) + +- 使用 TypeScript 严格模式 +- 遵循 React 最佳实践 +- 使用 Biome 进行代码格式化和检查 + +```bash +# 代码检查 +pnpm lint + +# 类型检查 +pnpm type-check + +# 代码格式化 +pnpm format +``` + +### 通用规范 + +- 变量和函数使用有意义的命名 +- 添加必要的注释，特别是复杂逻辑 +- 保持函数简短，单一职责 +- 避免硬编码，使用配置或常量 + +--- + +## 提交规范 + +我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。 + +### 提交格式 + +``` +(): + + + +