verifying-before-done

完成前的验证

必需背景： principal-engineering 技能。

概述

完成意味着已验证，而验证要说明检查了什么。认真工作不等于检查。

纪律

1. 在变更的实际运行路径上执行，并记录结果。 在运行中的系统里，沿着能执行变更代码的最短路径运行；下文的“在实际运行路径上验证”将对此作进一步说明。
2. 运行验证命令，并贴出其输出。 验证命令来自变更前的检查点；它用于证明各项门槛均已满足，其实际输出则为这部分声明提供依据。引用输出前，先对其中的机密值进行脱敏（机密信息处理由 operating-safely 负责）。“已验证”始终应写成“通过（检查了 X 和 Y）”，绝不能只打一个勾。
3. 如实报告，不偏不倚。 报告失败的测试及其输出，将跳过的步骤明确标为跳过，并直接陈述已验证的工作，不要含糊其辞。少报已验证的工作，会像夸大其词损害读者信任一样，浪费读者重新验证的时间。
4. 不要轻信全绿结果。 如果代码根本无法工作，测试套件却全绿，那就说明测试套件没有运行、未覆盖相关情况，或者无法失败。如果结果看起来过于完美，与变更规模不相称，就确认测试确实执行了（单独运行测试，观察它出现），并确认测试确实可能失败（破坏代码，观察测试变红，再还原代码）。从未运行的测试和从未触发的门槛，都会让人自信地错误宣称“已完成”。
5. 区分不同层级。 已实现（在代码仓库中）不等于已部署（在线上），也不等于已外部验证（在外部系统中检查过）。绝不能用较低层级的证据宣称达到了更高层级。
6. 声明完成前回顾检查。 全面检查差异：没有无关变更，代码或注释中没有残留的规划内容，同一变更中已更新文档，并且每项验收标准都确实达成，而非仅大致满足。
7. 对最高等级的变更进行独立验证。 变更的作者是最不适合验证该变更的人。对于项目声明的关键路径（资金、销售、存储的数据、安全等系统绝不能出错的事项）以及不可逆迁移，验证者必须是未编写该代码的人或系统。如果来不及找到独立验证者，就使用最接近的替代方案，并明确说明它属于较弱的验证形式；悄悄降低检查标准才是问题，公开说明并降低标准则是一项决定。

在实际使用场景中验证

门禁（verify 命令、测试套件、构建）只能证明仓库本身没问题；变更要在调用方实际使用它的地方才能得到验证：运行它的命令行、提供服务的端点、渲染内容的屏幕，或导入它的使用方。

• 在运行中的系统里，走最短路径执行变更后的代码。 使用变更后的标志运行命令，向变更后的处理程序发送请求，触发变更后的错误路径。内部函数不算实际使用场景：它的调用方最终会抵达某个实际使用场景，因此要在那里观察。
• 把测试视为作者提供的依据，而非验证本身。 测试说明要如何驱动；门禁会重新运行测试。
• 探测变更周边的情况。 正常路径能确认所述主张；相邻情况则能检验它：空值、重复调用、冲突选项，以及变更未涉及的相邻错误。至少要有一个超出主张范围的探测；即使探测结果正常，也要报告，因为它说明了覆盖范围。
• 引用系统实际产生的内容。 响应正文、终端输出和渲染后的屏幕，都是支持该主张的依据。引用前先删去令牌、连接字符串和身份验证标头。将含糊的输出视为失败，并附上已删去敏感信息的原始记录；绝不要将其解读为通过。
• 没有运行时实际使用场景时，就明确说明“没有运行时实际使用场景”。 不会产生行为的文档、注释和类型声明，应以此作为验证结果，绝不能用运行其他门禁来充数。
• 切勿在实际环境中触发破坏性路径。 如果变更后的代码会删除工作区以外的内容或向其写入数据，且没有安全的目标，则应验证相关路径，并指出未执行的路径（防护措施由 operating-safely 负责）。

你负责的失败门禁

先确定失败的来源，然后修复测试，无论测试归谁维护。“之前就有的问题”只能作为报告中的补充说明，绝不能成为门禁失败的借口。唯一例外是程序上的处理：主分支上已有的失败阻碍了一个无关修复的通过时，应明确说明情况，并提出仍然合并该通过修复的选项，由操作人员决定。

常见错误

• 只看差异看起来没问题，就宣布完成。差异只是待验证的假设；在实际使用场景中运行才是实验。
• 运行整个测试套件，而不是有针对性的 verify 命令，并把“没有新失败”当成“我的变更有效”。从未覆盖相关路径的测试套件无法为其背书。
• 重新运行门禁，就把它称为验证。门禁通过，但没有实际驱动使用场景，只能说明“CI 正常”，而非“变更有效”。
• 对风险在失败路径上的变更，只验证正常路径。
• 对风险来自环境（配置、迁移、权限、生产数据形态）的变更，最后只说“本地测试通过”。
• 红灯让人不便时，选择修测试而不是修代码。测试只是报信者。