From 043f0e7a2eea637ba41c92feaca7500fb600b542 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?= =?UTF-8?q?=29?= Date: Mon, 25 May 2026 20:41:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=AE=80=E5=8C=96=E8=B4=A1=E7=8C=AE?= =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=8C=E8=A1=A5=E5=85=85=E6=A1=8C=E9=9D=A2?= =?UTF-8?q?=E7=AB=AF=E6=89=8B=E5=B7=A5=E6=B5=8B=E8=AF=95=E5=92=8C=20PR=20?= =?UTF-8?q?=E5=BD=B1=E5=93=8D=E8=8C=83=E5=9B=B4=E8=A6=81=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 100 +++++++++++++++--------------------------------- 1 file changed, 31 insertions(+), 69 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23fb5697..0f7a3e6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,94 +1,56 @@ # 贡献指南 -感谢你帮助改进 Claude Code Haha。 +提交 PR 前需要完成以下三步。 -完整贡献指南包含本地检查、真实模型 baseline、质量门禁报告和 PR 要求： - -- 中文：[docs/guide/contributing.md](docs/guide/contributing.md) -- English：[docs/en/guide/contributing.md](docs/en/guide/contributing.md) - -大多数贡献者和 AI Coding Agent 在提交 PR 前应先运行统一入口： +## 1. 运行本地门禁 ```bash -bun install bun run verify ``` -`bun run verify` 等价于 `bun run quality:pr`，会根据 impact report 一键执行被选中的 policy、desktop、server、adapters、native、docs、quarantine 和 coverage 门禁。命令非 0 退出就表示当前分支还不能提交 PR 或 push。 +`bun run verify` 会一键检查 policy、desktop、server、adapters、native、docs、quarantine 和 coverage。非 0 退出就说明当前分支还不能提交 PR。 -这个门禁会同时生成质量报告和覆盖率报告。主质量报告会内嵌当前测试范围、结果矩阵、覆盖率摘要，并链接完整 coverage/JUnit/log artifact： +只改了某个模块时可以用窄命令快速迭代： -```text +| 改动范围 | 快速验证 | +| --- | --- | +| CLI / Server / 工具 | `bun run check:server` | +| 桌面端 | `bun run check:desktop` | +| IM Adapter | `bun run check:adapters` | +| Tauri / 原生 | `bun run check:native` | +| 文档 | `bun run check:docs` | + +门禁失败时，查看最新质量报告和对应 lane 日志定位问题： + +``` artifacts/quality-runs//report.md -artifacts/quality-runs//report.json -artifacts/quality-runs//junit.xml -artifacts/quality-runs//logs/*.log -artifacts/coverage//coverage-report.md +artifacts/quality-runs//logs/.log ``` -覆盖率 baseline/threshold 变更需要维护者加 `allow-coverage-baseline-change`。CI 会优先用 base branch 的 baseline 做 ratchet 对比，避免 PR 自己降低 baseline 后绕过门禁。覆盖率口径参考 Google/Microsoft 的公开实践：维护中的产品区域向 75-80%+ 拉升，新增或变更的可执行生产代码行必须满足 changed-line coverage 门槛。 -被 quarantine 的测试必须保留 owner、reviewAfter 和 exitCriteria；过期后 `check:quarantine`、`check:server`、`check:coverage` 都会阻断。 +## 2. 桌面端功能必须手工测试 -所有新功能和修复都必须遵守 `AGENTS.md` 里的 Feature Quality Contract：先说明变更面，再补同区域测试、覆盖率证据、必要的 E2E/live smoke 证据和剩余风险。AI Coding Agent 也要遵守 `.github/copilot-instructions.md`，不能只交生产代码不交测试证据。 +改动涉及 `desktop/` 的 UI、store、API 或 Tauri 原生层时，除了自动门禁外，还必须在真机上做手工测试： -给 AI 的修复循环可以直接写成： +- 起本地服务 `SERVER_PORT=3456 bun run src/server/index.ts` +- 起桌面端 `cd desktop && bun run dev` +- 验证改动涉及的交互流程：页面渲染、按钮/表单行为、弹窗、快捷键、多窗口等 +- 必要时打本地 macOS 包 `desktop/scripts/build-macos-arm64.sh` 做完整验证 -```text -Run `bun run verify`. If it fails, read the latest quality report and lane log, -fix missing same-area tests, coverage failures, type/lint/build errors, or -docs/native failures, then rerun `bun run verify` until the final Summary has -failed=0. Do not lower coverage baselines or thresholds unless a maintainer -explicitly requested it. -``` +## 3. PR 必须附上影响范围和测试说明 -常用定位路径： +每个 PR 的描述里必须包含： -- 总报告：`artifacts/quality-runs//report.md` -- lane 日志：`artifacts/quality-runs//logs/.log` -- 覆盖率报告：`artifacts/coverage//coverage-report.md` -- 机器可读覆盖率：`artifacts/coverage//coverage-report.json` +- **影响范围**：改了哪些模块（desktop / server / adapter / native / docs / provider / agent-loop） +- **测试说明**：跑了哪些测试、覆盖率情况、手工测试了哪些流程（桌面端改动必须有真机测试记录） +- **剩余风险**：已知未覆盖的边界或需要后续跟进的点 -如果希望本机在 `git push` 前强制运行同一套门禁，安装仓库 Git hook： - -```bash -bun run hooks:install -``` - -安装后，每次 push 都会先运行快速本地门禁（内部是 `bun run quality:push`）。它复用 PR gate 的 impact/policy/路径检查，但默认跳过耗时的 coverage lane；完整覆盖率仍保留在 `bun run verify`、`bun run quality:pr` 和 CI。维护者机器可以把真实模型/桌面 smoke 也纳入 pre-push： +如果改动了 provider/runtime、agent-loop、文件编辑、权限、session 等核心路径，还需要跑真实模型验证： ```bash bun run quality:providers -bun run hooks:install -- --live-provider-model :main +bun run quality:smoke --provider-model ``` -需要完整 live baseline 时加 `--live-mode baseline`。这个配置写入本机 `.git/config`，不会提交 provider 信息或密钥。 +## 更多 -如果当前分支包含 CLI core 或 coverage policy 这类维护者级变更，本机 hook 也不会默认放行。维护者需要显式配置本 clone 的批准： - -```bash -bun run hooks:install -- --allow-cli-core-change --allow-coverage-baseline-change -``` - -PR CI 由 `.github/workflows/pr-quality.yml` 在 PR 更新时触发。最后的 `pr-quality-gate` 会汇总所有被变更策略选中的 job；仓库 `main` 分支应在 GitHub branch protection / ruleset 中把 `pr-quality-gate` 设置成 required status check。 - -如果你在全新 clone 中运行 adapter 或 native 相关检查，还需要安装 adapter 依赖： - -```bash -cd adapters -bun install -``` - -如果改动涉及桌面端聊天路径、provider/runtime 选择、CLI bridge、权限、工具、文件编辑或发布打包，还需要用你本地可用的模型提供商跑真实 baseline： - -```bash -bun run quality:providers -bun run quality:gate --mode baseline --allow-live --provider-model :main -``` - -只想跑真实 provider/desktop smoke 时，可以使用： - -```bash -bun run quality:smoke --provider-model :main -``` - -发版前使用 `quality:gate --mode release --allow-live`，live lane 不允许静默跳过；如果缺 provider、额度或外部账号，要在报告里明确写 blocker。 +完整质量门禁和覆盖率说明见 [AGENTS.md](AGENTS.md)。