mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-16 13:03:31 +08:00
b156be8d8d
Contributors and coding agents need one local command that both reports and enforces the quality contract. This change turns the PR gate into the shared verification entrypoint, adds path-selected local lanes, tightens coverage accounting around changed lines, and documents the repair loop in contributor and agent-facing guidance. Constraint: Ordinary PR verification must stay non-live and runnable without provider credentials Constraint: Coverage policy updates in this commit require maintainer approval before push/merge Rejected: Keep quality guidance only in docs | agents need executable scripts and AGENTS.md instructions to follow the loop consistently Confidence: high Scope-risk: broad Directive: Do not bypass `bun run verify` for production changes; fix failed lanes and coverage reports instead of lowering thresholds Tested: bun run check:policy Tested: ALLOW_CLI_CORE_CHANGE=1 ALLOW_COVERAGE_BASELINE_CHANGE=1 bun run verify Not-tested: live provider baseline; no provider credentials were required for this non-live PR gate
95 lines
4.5 KiB
Markdown
95 lines
4.5 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你帮助改进 Claude Code Haha。
|
||
|
||
完整贡献指南包含本地检查、真实模型 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 前应先运行统一入口：
|
||
|
||
```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。
|
||
|
||
这个门禁会同时生成质量报告和覆盖率报告。主质量报告会内嵌当前测试范围、结果矩阵、覆盖率摘要，并链接完整 coverage/JUnit/log artifact：
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
覆盖率 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` 都会阻断。
|
||
|
||
所有新功能和修复都必须遵守 `AGENTS.md` 里的 Feature Quality Contract：先说明变更面，再补同区域测试、覆盖率证据、必要的 E2E/live smoke 证据和剩余风险。AI Coding Agent 也要遵守 `.github/copilot-instructions.md`，不能只交生产代码不交测试证据。
|
||
|
||
给 AI 的修复循环可以直接写成：
|
||
|
||
```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.
|
||
```
|
||
|
||
常用定位路径：
|
||
|
||
- 总报告：`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`
|
||
|
||
如果希望本机在 `git push` 前强制运行同一套门禁，安装仓库 Git hook：
|
||
|
||
```bash
|
||
bun run hooks:install
|
||
```
|
||
|
||
安装后，每次 push 都会先运行同一套验证入口（内部是 `bun run quality:pr`，等价于 `bun run verify`），失败则 push 中止。维护者机器可以把真实模型/桌面 smoke 也纳入 pre-push：
|
||
|
||
```bash
|
||
bun run quality:providers
|
||
bun run hooks:install -- --live-provider-model <selector>:main
|
||
```
|
||
|
||
需要完整 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。
|