为 Kubernetes 增删一致性测试后如何更新 conformance.yaml 黄金列表

在 Kubernetes 仓库中新增或移除一个带 [Conformance] 标签的一致性测试（conformance test）后，控制"一致性测试全集"的回归测试会失败：它要求测试代码中实际存在的 conformance 测试与仓库里签入的黄金列表（golden list）test/conformance/testdata/conformance.yaml 完全一致，任何增删都会让二者产生 diff。test/conformance/README.md 明确说明：增删 conformance 测试后必须更新 testdata/ 中的黄金列表，且该文件的变更需要 sig-architecture 评审。本文按"确认失败原因 → 运行更新脚本 → 验证 → 提交 PR"的路径说明如何完成这件事。

回归测试如何检查黄金列表

失败判定来自 test/conformance/conformance_test.sh，它的逻辑只有两行：

if diff -u test/conformance/testdata/conformance.yaml test/conformance/conformance.yaml; then
  echo PASS
  exit 0
fi
echo 'See instructions in test/conformance/README.md'
exit 1

即逐行对比黄金列表与最新生成的 conformance 测试列表：一致则输出 PASS；不一致则退出码为 1，并提示去 test/conformance/README.md 查更新方法。你在 CI 或本地测试流水线上看到的失败现象就是这两者之一：diff 输出里出现新增/删除的测试条目，或脚本打印的提示行。

conformance.yaml 里每条记录从哪里来

conformance.yaml 中每个条目包含 testname、codename、description、release、file 五个字段，例如：

- testname: Priority and Fairness FlowSchema API
  codename: '[sig-api-machinery] API priority and fairness should support FlowSchema
    API operations [Conformance]'
  description: ' The flowcontrol.apiserver.k8s.io API group MUST exist in the /apis
    discovery document. ...'
  release: v1.29
  file: test/e2e/apimachinery/flowcontrol.go

这些数据由 test/conformance/walk.go 生成：它解析 test/e2e 测试源码中每个 ConformanceIt 块上方注释里的 Testname:、Description:、Release: 字段。其中 Testname 是必需的，Release 可选（walk_test.go 中 "Testname but no Release does not result in nil" 用例说明了这一点）。生成时 walk.go 还会对测试名做 validateTestName 校验：含 [Flaky]、[Feature:xxx]、[Alpha] 等标签的测试名会被拒绝，报错形如 '...' cannot have invalid tags ...；而 [LinuxOnly]、[Serial]、[Disruptive]、[NodeConformance] 等标签是合法的。

因此，往黄金列表里加一个测试，实质是在 test/e2e 下新增一个带 [Conformance] 标签、且注释含 Testname:/Description:（可选 Release:）的 ConformanceIt；移除测试则相反。列表内容本身不应手工编辑，README 指定的更新方式只有运行脚本。

更新前的准备

• 完整的 Kubernetes 源码 checkout，所有命令在仓库根目录下执行。
• 更新脚本内部会调用 hack/make-rules/build.sh 编译 ginkgo 和 e2e.test 二进制，并调用 hack/lib/init.sh 里的 kube::golang::setup_env 准备 Go 环境，所以机器上需要满足仓库要求的 Go 工具链和构建依赖。
• 副作用范围可控：整个流程只写 _output/ 下的构建产物（_output/bin/、_output/specsummaries.json、_output/conformance.yaml）和被更新的 test/conformance/testdata/conformance.yaml，不需要集群。生成列表这一步用的是 --dry-run=true，只 dump spec，不会真正执行 e2e 测试。

运行更新脚本

在仓库根目录执行：

hack/update-conformance-yaml.sh

hack/update-conformance-yaml.sh 做两件事：先调用 test/conformance/gen-conformance-yaml.sh 生成新的 conformance.yaml，再把 _output/conformance.yaml 覆盖复制到签入位置 test/conformance/testdata/conformance.yaml。

生成链路的实际内容是：

1. gen-specsummaries.sh 编译 ginkgo 与 e2e 测试二进制：

   DBG=1 hack/make-rules/build.sh github.com/onsi/ginkgo/v2/ginkgo test/e2e/e2e.test
   

   然后以 dry-run 方式 dump 所有 [Conformance] 标签的测试 spec：

   ./_output/bin/ginkgo --dry-run=true --focus='[Conformance]' ./_output/bin/e2e.test -- --spec-dump "${KUBE_ROOT}/_output/specsummaries.json" > /dev/null
   

   注意 --focus='[Conformance]'：只有测试名中带 [Conformance] 标签的测试会进入黄金列表。

2. spec-to-yaml.sh 在 kube::golang::setup_env 之后执行：

   go run ./test/conformance/walk.go --source="${KUBE_ROOT}" ./_output/specsummaries.json > ./_output/conformance.yaml
   

   把 spec dump 转成最终的 yaml。

脚本设置了 set -o errexit，任何一步失败（编译不过、validateTestName 校验失败等）都会直接中止，此时 _output/conformance.yaml 未被生成，签入的黄金列表也不会被改动。首次运行需要完整编译 ginkgo 和 e2e.test，耗时较长属于正常现象。

验证更新结果

按下面三步确认黄金列表已正确收敛：

1. 审查 diff 范围：

   git diff -- test/conformance/testdata/conformance.yaml
   

   黄金列表是全量重新生成的，diff 里应只有与你新增/移除的测试对应的条目（testname/codename/description/release/file）。如果出现你本次并未改动的测试条目，说明工作区里还有其他未预期的测试文件改动，应先在 diff 里定位这些改动。

2. 幂等性自检：再运行一次 hack/update-conformance-yaml.sh，若第二次运行后 git diff 无新增变化，说明黄金列表已与测试代码完全同步，回归对比不会再失败。

3. 直接查看黄金列表内容。更新脚本已经把 e2e.test 编译到 _output/bin/，而 test/e2e/e2e_test.go 的 TestMain 提供了 --list-conformance-tests 入口：它会读取 test/conformance/testdata/conformance.yaml 并把全部条目（Testname/Codename/Description/Release/File 字段）打印到 stdout：

   ./_output/bin/e2e.test --list-conformance-tests
   

   在输出中确认你新增的测试名已出现、移除的测试名已消失，即可说明黄金列表更新到位。

提交变更与限制

• README 要求的收尾动作只有一条：把变更后的 test/conformance/testdata/conformance.yaml 加入你的 PR 送审。该文件变更需要 sig-architecture 评审，这是文档明确给出的流程约束。
• 黄金列表由脚本全量重新生成。测试代码注释（Testname:/Description:/Release:）写什么，列表里就是什么；如果校验不通过（如测试名带非法标签），脚本会中止而不是生成一个带错的文件。
• 本文路径只覆盖"增删 conformance 测试后同步黄金列表"这一任务；运行完整的 conformance 测试套件本身由 test/conformance/conformance_test.sh 所在的测试流水线负责，不属于这里要执行的内容。