#贡献指南

如何为 eval_752 做贡献。

#开始之前

1. Fork 仓库
2. Clone 你的 fork
3. 安装 pre-commit hooks：

   uvx pre-commit install
   uvx pre-commit install --hook-type commit-msg

#开发工作流

1. 创建 feature branch：git checkout -b codex/your-feature
2. 进行修改
3. 编写测试
4. 运行质量检查：python check.py
5. 使用 Conventional Commits 提交
6. 推送并创建 PR

#提交规范

feat(scope): add new feature

Detailed description of changes.

类型：feat、fix、docs、test、refactor、chore、perf

#质量门禁

所有 PR 都必须：

• 通过 lint（ruff、eslint）
• 通过类型检查（mypy、tsc）
• 通过测试（后端保持 100% branch-aware coverage）
• 为新功能补充测试
• 更新相关文档

#本地化检查清单

如果你的变更涉及面向用户的文案：

• 在 locales/en/frontend.json 或 locales/en/backend.json 中新增或修改 key
• 在所有支持语言中保持相同 key 结构
• 验证浏览器跟随模式与 Settings 中的手动语言覆盖
• 不要在组件、hooks、API routes 中写内联 fallback English

完整流程见 国际化。

#代码评审

PR 会重点审查：

• 正确性
• 测试覆盖
• 文档
• 性能
• 安全性

开发环境 setup 见 开发总览。

#文档开发（Rspress v2）

我们现在使用 docs/ 目录下的 Rspress v2 发布文档。 英文内容位于 docs/en/，简体中文位于 docs/zh/，共享静态资源位于 docs/public/。

#安装与本地预览

cd docs
pnpm install
pnpm dev

#构建与验证

cd docs
pnpm build

#Analytics

• 文档站通过 docs/theme/index.tsx 初始化 posthog-js，不再依赖零散的 inline 页面脚本。
• 本地预览 host（localhost、127.0.0.1、::1、0.0.0.0）默认排除，因此 pnpm dev 与本地 preview 不会污染生产 docs analytics。
• 当前埋点范围刻意保持收敛：只覆盖 SPA pageview 与 link/button autocapture；session replay 与 surveys 默认关闭，后续若要扩范围必须单独补计划。

#链接与资源

• 在 locale 树内优先使用相对链接，例如 ../operations/configuration.md
• 对 docs/ 目录外的文件（如 specs/）使用 GitHub blob URL
• 共享图片统一放在 docs/public/，通常使用 docs/public/screenshots/<locale>/
• 优先使用 Markdown、MDX 组件和 Rspress 内建能力，不要随意嵌入脚本
• 品牌资源（logo、icon）位于 docs/public/brand/
• locale 导航定义在 docs/en/_nav.json 与 docs/zh/_nav.json，section 顺序定义在 _meta.json

#Redirects

历史路由跳转通过 docs 内容树中的轻量 redirect 页面实现。

#CI

deploy-docs 工作流会在 docs/ 中使用 pnpm 安装依赖，并发布 Rspress 构建产物。