CONTRIBUTING
贡献指南
从分支与 worktree 准备，到验证、提交和 PR 证据，形成可评审的单一逻辑变更。
先说结论
一项可合并的 Super Dolphin 贡献，需要范围清楚、证据完整，也要让维护者能够复查。代码写完只是中间状态；守卫、生成地图、测试和人工评审都属于交付的一部分。
公开仓库地址保留为 Super-Dolphin，但当前匿名访问仍不可用。正式公开前，只有已有权限的维护者可以使用现有 checkout 与 remote；不要把目标 URL 当成已经开放的 fork、issue 或 PR 入口。
怎么理解
一项可评审贡献应同时满足四层要求：
| 层次 | 需要回答的问题 | 典型证据 |
|---|---|---|
| 意图 | 为什么要改，验收结果是什么？ | 单一问题描述、复现或设计目标 |
| 边界 | 哪些文件和行为应改变，哪些不应改变？ | 聚焦 diff、明确非目标 |
| 验证 | 什么证明改动有效且没有破坏约束？ | 测试、guard、生成物检查、构建结果 |
| 风险 | 还剩哪些兼容、安全、回滚或环境风险？ | PR 风险说明、已知限制与失败记录 |
每个分支和 PR 只承载一个逻辑任务。不要把无关格式化、依赖升级、生成物刷新或顺手修复混入同一变更。
怎么使用
- 阅读行为准则；漏洞转到支持与安全，不要进入公开 issue 或 PR。
- 从最新、干净的基线创建聚焦分支。并行任务使用独立 Git worktree。
- 在 linked worktree 中运行
make codex-worktree-ready、go run ./cmd/codex-worktree-setup ready与verify，然后新开 Agent 任务加载该 checkout 自己的 LSP peer。 - 先复现缺陷或写清验收条件，再做能解决已证实原因的最窄修改。
- 按变更面执行验证，并在 PR 中记录完整命令与结果。
| 变更面 | 最低验证 |
|---|---|
| 仅文档 | git diff --check |
| 聚焦 Go package | 对实际变更 package 运行受 guard 保护的测试 |
| 架构规则或 guard 基线 | make guard |
| 跨层或大范围 Go 变更 | make test 与 make build-plain |
| React 前端 | npm run lint、npm test、npm run build |
| SQL 或 Store 生成 | make sqlc-verify 与受影响 package 测试 |
| Code/Project/Capability map | 对应 *-check 目标 |
- 提交标题必须包含中文；
fix、hotfix、bugfix或“修复”提交必须同时包含能锁定缺陷的测试、fixture、golden file 或 snapshot。 - PR 写明问题、预期结果、改动范围、复现或验收证据、验证命令、剩余风险和回滚方式。
常见问题
- Worktree readiness 失败：修复当前 checkout 的本地配置或 binary，不复用其他 checkout 的 LSP 结果。
- Guard 或生成物检查失败：找到所属真源；只有真源确实变化时才运行 refresh，不能手改生成结果压绿。
- Hook 拒绝提交：修复标题、正文或缺失的 bug-locking evidence，不使用
--no-verify绕过。 - 验证中曾出现失败：保留并解释原始失败；一次通过的重跑不能证明之前的失败没有发生。
- PR 范围失控：拆分无关任务，确保每个提交都处于可验证状态。
适用范围
- 不提交凭据、Provider home、本地数据库、用户 Memory、私密 trace、未脱敏日志或机器路径。
- 不移除边界检查、silent fallback 或空 catch 来换取表面成功；无效配置与缺失依赖应 fail-fast。
- 第三方 vendored source 的许可证和归属不能被删除或错误改写。
- 当前公共 fork、issue 和 PR 流程尚未开放；以下规则适用于发布后的贡献流程和现有维护者。