质量保证 SOP¶

结论：用风险分级、自动验证、可控发布和运行复盘保证变更质量。

0. 文档控制¶

1. 目的与范围¶

本 SOP 适用于 2 到 15 人、使用 GitHub 的个人仓库或组织仓库。团队规模是经验值。

流程覆盖需求、设计、开发、代码审查、持续集成（CI）、合并、发布、运行反馈和复盘。

流程目标有三项：

1. 阻止已知高风险问题进入默认分支。
2. 限制发布失败对用户的影响范围。
3. 让缺陷、回滚和告警进入改进循环。

本 SOP 是 研发工作流 的质量补充。本文不替代原工作流。

本 SOP 不承担 ISO 27001、SOC 2 等外部合规取证。外部取证要求单独定义。

2. 质量定义¶

一次变更同时满足以下五项，才算达到质量要求。

• 变更满足可验证的验收标准。
• 变更覆盖必要的测试。
• 变更没有未处理的高风险问题。
• 发布路径可观测、可回滚。
• 每项风险都有明确负责人。

测试数量、覆盖率和通过率只是信号。单一数字不能单独代表质量。

3. 角色¶

单人仓库由负责人执行维护人检查。检查结果仍要记录。

4. 风险分级¶

负责人创建 issue 时填写风险等级。风险等级由用户影响和恢复难度共同决定。

Priority P0 到 P3 表示交付优先级。Risk R0 到 R3 表示质量风险。两个字段独立填写。

只要变更涉及权限、认证、支付、用户数据、生产凭据或发布链路，风险等级最低为 R0。

团队不足 2 名审查人时，R0 变更还要增加发布后验证。维护人记录例外、批准人和失效日期。

风险等级填写在 Project 字段 Risk 中。风险等级变化时，负责人在 issue 正文记录变化原因。

5. 主流程¶

下图展示质量活动的顺序和反馈关系。

flowchart LR
  A["风险分级"] --> B["验收标准与测试方案"]
  B --> C["小批量开发与自测"]
  C --> D["代码审查与自动检查"]
  D --> E["Merge queue"]
  E --> F["Canary 与运行监控"]
  F --> G["复盘、指标与规则更新"]
  G --> A

5.1 步骤¶

本文统一使用 GitHub 功能名 Merge queue。

每个变更通过 Pull Request（PR）交付。PR 必须包含目的、测试和风险。

5.2 小批量规则¶

一个 PR 只解决一个完整问题。独立重构与功能变更分开提交。

无法快速审查的 PR，负责人先拆分。拆分不改变验收标准。

6. 完成标准（Definition of Done）¶

负责人提交 PR 前，逐项检查以下条件。

• 验收标准可验证。
• 变更覆盖新增或修改的行为。
• 必需 CI 检查通过。
• 代码审查由非作者完成。
• 审查对话全部解决。
• CodeQL、密钥扫描和依赖扫描没有未处理的高风险问题。
• 数据库、配置和权限变更包含回滚方案。
• R0、R1 变更包含监控项和告警负责人。
• 测试、发布和风险证据链接到 issue。
• PR 不包含无关改动。

覆盖率门禁可选。启用时，默认要求变更行的覆盖率不得低于目标分支。团队按语言和项目调整阈值。

7. 代码审查规则¶

审查人先判断变更是否应该存在，再判断代码是否正确。

审查顺序如下。

1. 对照验收标准检查行为。
2. 检查失败路径、边界条件和权限。
3. 检查测试是否覆盖真实风险。
4. 检查数据迁移、兼容性和回滚。
5. 检查日志、指标和告警。
6. 检查命名、结构和可维护性。

审查意见分为三类：必须修改、建议修改、问题讨论。必须修改项关闭前不得批准。

人工智能（AI）初审可以处理重复问题和明显缺陷。人工审查负责架构、产品权衡、权限、隐私和发布风险。Merge 责任仍由开发者承担。

8. GitHub 原生控制¶

8.1 一次性配置¶

1. 在 Project 增加 Risk 字段。
2. 在 PR 模板增加目的、测试、风险、回滚和证据。
3. 在 Ruleset 启用 PR、审查、必需状态检查和对话解决。
4. 在生产 Environment 启用审批规则。
5. 为 R0、R1 服务启用 CodeQL、密钥扫描和 Dependabot。
6. 记录规则集绕过名单。

8.2 控制清单¶

规则集绕过权限只授予指定管理员。维护人每季度复核一次绕过名单。

部分控制受 GitHub 套餐限制。功能不可用时，维护人记录替代控制和剩余风险。替代控制不能伪装成自动门禁。

9. 发布规则¶

9.1 R0 发布¶

1. 在发布前确认回滚版本和负责人。
2. 写清 Canary 的观察窗口和停止阈值。
3. 向小比例生产流量发布 Canary。
4. 观察错误、延迟、饱和度和业务指标。
5. Canary 达标后分批扩大流量。
6. 出现严重告警、SLO 超限或核心指标偏移时停止扩量。
7. 出现用户影响时先回滚或关闭功能，再定位根因。
8. 在 issue 写发布结果和后续动作。

Canary 观察窗口默认 30 分钟。低流量或高延迟服务延长到样本量足够为止。

9.2 R1 发布¶

1. 在低风险时段发布。
2. 观察发布窗口内的错误和延迟。
3. 出现用户影响时暂停或回滚。
4. 在发布记录中写结果。

9.3 R2、R3 发布¶

按标准流程发布。发布失败时记录原因和修复链接。

10. 测试可靠性¶

flaky test 指同一代码同时出现通过和失败结果的不稳定测试。

红灯必须可信。团队不能依赖反复重跑获得绿色结果。

维护人按以下顺序处理 flaky test：

1. 记录测试名、提交、分支、构建和失败现象。
2. 对同一代码重跑，判断结果是否稳定。
3. 按影响面排序。优先处理高频、跨分支和阻塞部署的问题。
4. 自动重跑只能暂时隔离失败，不能代替修复。
5. 为高频 flaky test 建 issue、指定负责人和截止日期。
6. 修复后保留验证记录。

默认指标为 Flaky Build Rate，即因 flaky test 失败的构建占比。前 4 周采集基线，不先设强制目标。

11. 质量指标¶

维护人每周记录以下指标。

前 4 周只采集基线。第 5 周开始设目标，每次只改一个指标。

指标不得用于个人排名。指标用于发现系统问题。

12. 例外与热修¶

下列情况可以走例外流程：

• 生产事故需要立即恢复服务。
• 外部依赖故障阻塞关键发布。
• 规则集或扫描工具自身故障。

例外执行规则：

1. 开一个 incident issue。
2. 记录绕过原因、影响范围、批准人和失效时间。
3. 只绕过与事故直接相连的质量门禁。
4. 恢复服务后补做检查。
5. 在 2 个工作日内补完验证或回滚。
6. 把根因和长期修复写进 incident issue。

静默绕过是流程缺陷。每次绕过都要进入月度质量复核。

13. 事件与复盘¶

事件复盘只讨论系统和流程，不追究个人责任。

复盘至少回答五项：

1. 用户受到什么影响。
2. 事件何时开始、何时被发现、何时恢复。
3. 哪个控制缺失、失效或未被使用。
4. 哪个动作缩短了影响时间。
5. 哪个负责人会在何时验证改进。

复盘动作必须进入 issue，并设置截止日期。没有验证动作的复盘不算完成。

14. 每周质量复核¶

维护人每周执行以下检查。

1. 查看未关闭的 R0、R1 风险和逾期动作。
2. 查看 Change Failure Rate、Time to Restore 和 Flaky Build Rate。
3. 查看规则集绕过记录。
4. 查看超过期限的例外。
5. 抽查 1 到 3 个近期 PR 的质量证据。
6. 为异常指标指定负责人和下周动作。
7. 把复核结论写进固定 issue 或项目记录。

每周复核控制在 30 分钟内。超过 30 分钟时，减少指标或自动采集。

15. 上线顺序¶

团队首次采用本 SOP 时，按以下顺序执行。

1. 给 1 个仓库启用 PR、代码审查和必需检查。
2. 给第一个仓库增加 CodeQL、密钥扫描和 Dependabot。
3. 给高并发目标分支启用 Merge queue。
4. 给生产环境增加审批和回滚记录。
5. 选择 1 个 R0 或 R1 服务启用 Canary 和 SLO。
6. 连续 4 周采集质量指标。
7. 根据基线设置第一个质量目标。
8. 扩展到更多仓库。

先在第一个仓库完成验证，再扩展到组织。不要一次启用全部门禁。

16. 记录与证据¶

正文保留结论。评论保留讨论过程。关键结论必须写回 issue 或 PR 正文。

17. 常见误读¶

• 误读：测试越多，质量越高。
  正确做法是让测试对风险有代表性，并保持红灯可信。

• 误读：覆盖率达标就可以合并。
  正确做法是同时检查行为、风险、扫描和发布条件。

• 误读：所有问题同等优先。
  正确做法是按影响面、频率和恢复难度排序。

• 误读：速度与质量冲突。
  正确做法是减少等待、缩小批量、自动收集证据。

• 误读：AI 可以承担发布责任。
  正确做法是使用 AI 初审，由开发者承担 Merge 责任。

18. 评审与生效¶

用户负责内容验收。维护人负责流程检查。

1. 用户审阅风险分级、质量门禁、发布规则和指标。
2. 用户记录批准或退回意见。
3. 退回时保持 review，按意见修改。
4. 批准后将 status 改为 active。
5. 批准后将 version 改为 1.0。
6. 填写生效日期并更新 updated。

19. 调研依据¶

本 SOP 依据 GitHub 公开工程实践整理。阈值和角色配置是团队默认值，不宣称为 GitHub 内部规则。

1. GitHub Engineering Fundamentals（2024-02-08）
2. GitHub Merge Queue（2024-03-06）
3. Reducing flaky builds by 18x（2020-12-16）
4. Making GitHub CI workflow 3x faster（2020-10-29）
5. Deployment reliability at GitHub（2021-02-03）
6. Building On-Call Culture at GitHub（2021-01-06）
7. SERVICEOWNERS at GitHub（2023-12-19）
8. Code review in the age of AI（2025-07-14）
9. GitHub Code Quality（访问：2026-10-28）
10. GitHub Rulesets（访问：2026-10-28）

20. 版本记录¶