mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-17 13:13:35 +08:00
docs: 简化贡献指南，补充桌面端手工测试和 PR 影响范围要求
This commit is contained in:
程序员阿江(Relakkes)
parent
c4890bdafc
commit
043f0e7a2e
100
CONTRIBUTING.md
100
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/<timestamp>/report.md
|
||||
artifacts/quality-runs/<timestamp>/report.json
|
||||
artifacts/quality-runs/<timestamp>/junit.xml
|
||||
artifacts/quality-runs/<timestamp>/logs/*.log
|
||||
artifacts/coverage/<timestamp>/coverage-report.md
|
||||
artifacts/quality-runs/<timestamp>/logs/<lane>.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/<timestamp>/report.md`
|
||||
- lane 日志：`artifacts/quality-runs/<timestamp>/logs/<lane>.log`
|
||||
- 覆盖率报告：`artifacts/coverage/<timestamp>/coverage-report.md`
|
||||
- 机器可读覆盖率：`artifacts/coverage/<timestamp>/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 <selector>:main
|
||||
bun run quality:smoke --provider-model <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 <selector>:main
|
||||
```
|
||||
|
||||
只想跑真实 provider/desktop smoke 时，可以使用：
|
||||
|
||||
```bash
|
||||
bun run quality:smoke --provider-model <selector>:main
|
||||
```
|
||||
|
||||
发版前使用 `quality:gate --mode release --allow-live`，live lane 不允许静默跳过；如果缺 provider、额度或外部账号，要在报告里明确写 blocker。
|
||||
完整质量门禁和覆盖率说明见 [AGENTS.md](AGENTS.md)。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user