Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (65 loc) · 4.57 KB

CONTRIBUTING.md

File metadata and controls

94 lines (65 loc) · 4.57 KB

贡献指南

感谢你帮助改进 Claude Code Haha。

完整贡献指南包含本地检查、真实模型 baseline、质量门禁报告和 PR 要求：

大多数贡献者和 AI Coding Agent 在提交 PR 前应先运行统一入口：

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：

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 的修复循环可以直接写成：

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：

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：

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 的批准：

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 依赖：

cd adapters
bun install

如果改动涉及桌面端聊天路径、provider/runtime 选择、CLI bridge、权限、工具、文件编辑或发布打包，还需要用你本地可用的模型提供商跑真实 baseline：

bun run quality:providers
bun run quality:gate --mode baseline --allow-live --provider-model <selector>:main

只想跑真实 provider/desktop smoke 时，可以使用：

bun run quality:smoke --provider-model <selector>:main

发版前使用 quality:gate --mode release --allow-live，live lane 不允许静默跳过；如果缺 provider、额度或外部账号，要在报告里明确写 blocker。