PR 工作流
面向维护者的 PR 治理合同，适用于目标分支为 master 的 PR。分支保护设置、DoR/DoD 就绪合同以及故障恢复协议均在此处。日常审查工作详见 审查者手册。面向贡献者的流程请参见 如何贡献。
治理目标
该工作流的存在是为了在高 PR 量下保持以下五项内容正确无误：
- 合并吞吐量是可预测的。
- CI 信号质量保持高水平——反馈迅速，误报率低。
- 安全审查明确针对高风险区域。
- 变更易于理解和回滚。
- 仓库中的工件不包含个人或敏感数据。
实现这一功能的控制循环是分层设计的：
- 摄入分类 — 路径/大小/风险标签将 PR 路由到正确的深度。
- 确定性验证 — 合并门控依赖于可复现的检查，而非主观评论。
- 基于风险的审查深度 — 高风险路径进行深度审查，低风险路径保持快速。
- 先回滚的合并契约 —— 每个合并路径都包含一个具体的恢复故事。
自动化处理入库标签和 CI 门禁。最终的合并责任仍由人工维护者和 PR 作者承担。
Project board contract
The Project board is an automated planning board, not the authoritative PR review queue.
Use the board for issue readiness, active ownership, roadmap grouping, dependencies, blocker state, and stale-exemption reasons. Those signals move slowly enough that a board field or planning lane can stay useful.
A draft JSON summary of this planning split lives in project-board-contract.json. Treat it as design input for future board refresh automation, not as an active GitHub Project integration yet.
Do not mirror native PR review state into manual board lanes. GitHub PR state owns review decision, required checks, mergeability, conflicts, stale approvals, and merge readiness. If the board later displays derived PR routing such as DIRTY, BEHIND, or APPROVED, treat it as a dashboard view of GitHub state, not a separate source of truth.
This keeps the board useful without asking maintainers to update it after every push, review, or CI run.
PR lanes
PR lanes are routing expectations, not another required label family. Use them to decide how much review depth, sequencing, and maintainer attention a PR needs. CODEOWNERS, native GitHub review state, CI, labels, linked issues, and explicit relationship keywords still carry the actual routing data.
| Lane | Common examples | Expected movement |
|---|---|---|
| A: maintenance fast lane | Docs-only corrections, small tests that leave behavior unchanged, metadata/template fixes, narrow examples, CI/tooling fixes that preserve permissions and release behavior | Lightest review; fast merge once CI, template, labels, and privacy checks are clean. Usually risk: low and size: XS or size: S. |
| B: narrow bug/fix lane | Small bug fixes with clear failing behavior, targeted provider/channel/tool fixes with focused validation, compatibility fixes that preserve behavior outside the reported path | Normal review by one subsystem-aware reviewer unless risk or ownership says otherwise. Merge when the linked issue is actually satisfied, validation is credible, and CI is green. |
| C: feature slice lane | Additive feature work, new provider/channel/tool support, new config surface, scoped user-visible behavior changes | Normal review plus boundary-specific validation. Milestone fit matters, and the PR should say whether it implements, depends on, or is related to a tracker. |
| D: architecture, migration, and high-risk lane | Runtime, gateway, security, tool-execution, workflow, broad crate migration, lifecycle, persistence, provider payload, channel behavior, permission, or release-infrastructure changes | Deep review, stronger local and CI evidence, rollback and compatibility analysis, and possible milestone sequencing or second-maintainer review. |
| E: supersede, replacement, and overlap lane | Multiple PRs solving the same issue, newer PRs replacing older ones, contributor work carried forward from another PR, old PR made obsolete by current master | Coordinate before deep review. Choose one canonical path when possible, use Supersedes #N only when accurate, and preserve attribution when work is materially carried forward. |
Do not build a separate manual PR board for these lanes unless native GitHub state and CODEOWNERS stop answering the routing question. Check native GitHub merge state before normal lane review: DIRTY means resolve conflicts first; BEHIND alone is mergeability housekeeping, not an author-facing blocker.
必需的仓库设置
master 分支的保护设置：
- 合并前要求状态检查。
- 需要检查
CI Required Gate。 - 合并前需要拉取请求审查。
- 为受保护的路径要求 CODEOWNERS 审查。
- 对于
.github/workflows/**，通过CI Required Gate（WORKFLOW_OWNER_LOGINS）要求所有者批准；将分支/规则集绕过限制为仅限组织所有者。 - 默认的工作流所有者白名单通过
WORKFLOW_OWNER_LOGINS仓库变量进行配置（当前列表请参阅 CODEOWNERS）。 - 当推送新提交时，撤销过期的审批。
- 限制强制推送。
- 所有贡献者的 PR 都直接指向
master分支。
就绪定义（DoR）
在请求审查之前，PR 应具备以下内容：
- PR 模板已完整填写。
- 明确范围边界（哪些内容已更改 / 哪些内容未更改）。
- 已附上验证证据——实际的命令输出，而非“CI 将进行检查”。
- 高风险路径的安全与隐私及回滚字段已填写完毕。
- 隐私和数据清理规则已满足 — 中性、项目范围的测试用语。参见 隐私。
- 不可避免时，身份类表述使用 ZeroClaw / 项目原生标签。
完成定义（DoD）
合并前：
CI Required Gate为绿色。- 已批准所需的审阅者（包括任何 CODEOWNERS 路径）。
- 风险标签与触碰的路径匹配。请参阅 Labels。
- 迁移/兼容性影响已记录。
- 回滚路径具体且快速。
维护者合并检查清单
每次合并：
- 范围明确且易于理解。
- CI 门禁已通过。
- 当文档发生变化时，文档质量检查已通过。
- 安全和隐私字段已完整；证据已脱敏/匿名化。
- 如果使用了 AI 辅助，工作流笔记足以保证可复现性。
- 回滚计划是明确的。
- 提交标题遵循 Conventional Commits 规范。
使用 squash-merge 并保留完整的提交历史在提交信息中。squash-merge 技能会生成紫色的 已合并 徽章以及符合 conventional-commits 格式的提交信息 — 有关调用方式，请参阅 Skills。
AI / 代理贡献政策
欢迎使用 AI 辅助的 PR。审查也可以由代理辅助完成。
必需：
- 清除 PR 摘要，明确范围边界。
- 明确的测试/验证证据。
- 高风险变更的安全影响和回滚说明。
推荐：
- 当自动化显著影响变更时，简要的工具/工作流说明。
- 用于可复现性的可选提示/计划片段。
我们不要求贡献者量化 AI 与人工的行所有权。差异和验证证据足以说明问题。
对于 AI 相关的 PR，审查者会重点关注：
- 合同兼容性。
- 安全边界。
- Error handling.
- 性能和内存回归。
- 作者是否能够回答关于行为和影响范围的问题（意图理解）。
审查服务等级协议（SLA）和队列规则
- 首要维护者审查目标：48 小时内。
- 被阻止的 PR 会收到一个可操作的清单评论，而不是一系列部分审查。
status:no-staleis reserved for accepted or otherwise long-lived work with a recorded reason to stay open when the issue is not already protected by another stale exclusion.
对于堆叠工作，要求显式使用 Depends on #...，以确保审查顺序是确定的。
对于替换操作，必须显式使用 Supersedes #...。有关归属和模板规则，请参阅 替换 PR。
审查者端的队列管理——积压项的修剪顺序、过期处理、标签清理——详见 审查者手册。
安全性和稳定性规则
这些路径需要更严格的审查和更强的测试证据：
crates/zeroclaw-runtime/src/security/crates/zeroclaw-runtime/的其余部分crates/zeroclaw-gateway/（入口、身份验证、配对）crates/zeroclaw-tools/（任何具有执行能力的组件）- 文件系统访问边界。
- 网络与认证行为。
.github/workflows/和发布流水线。
高风险 PR 的最低要求： 威胁/风险说明、缓解措施说明、回滚步骤。
适用于高风险 PR： 一个聚焦于边界行为的测试，以及一个明确展示预期退化情况的故障模式场景。
对于这些路径上的代理辅助贡献，审查者还会验证作者能否阐述运行时行为和影响范围——而不仅仅是粘贴验证输出。
故障恢复
如果合并的 PR 导致回归：
- 立即在
master上执行 revert。 - 打开一个带有根本原因分析的后续问题。
- 重新引入该修复，并附带覆盖该失败模式的回归测试。
优先快速恢复服务质量，而非延迟的完美修复。