From 3cdf862cf2ddb7efdec88f281c90848be7e39853 Mon Sep 17 00:00:00 2001 From: Wei Cao Date: Tue, 19 May 2026 12:32:42 +0800 Subject: [PATCH 1/2] docs: add controller diagnostic PR scope guide --- docs/code-submission/README.md | 1 + ...on-controller-diagnostic-pr-scope-guide.md | 84 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md diff --git a/docs/code-submission/README.md b/docs/code-submission/README.md index e123cd4..fc2d4f6 100644 --- a/docs/code-submission/README.md +++ b/docs/code-submission/README.md @@ -10,3 +10,4 @@ - [`addon-design-contract-review-during-xp-guide.md`](addon-design-contract-review-during-xp-guide.md) — XP / pair-programming 代码 review 阶段的 8 类设计契约级缺陷 checklist（silent fallback / 非空字段未强制 / 同 commit state 不连续 / sentinel 值传错误 / 条件清理状态枚举不穷尽 / NotFound 短路写入 / terminating vs absent / 运算符优先级） - [`addon-spec-field-zero-vs-unset-guide.md`](addon-spec-field-zero-vs-unset-guide.md) — Class 4 (sentinel value confusion) 在 spec field 上的展开：spec 零值 vs 字段不存在的反模式识别 + 4 种正确区分方法 + 验收路径与执行路径必须一致的修复口径 - [`addon-promql-rule-pack-peer-review-blocker-class-guide.md`](addon-promql-rule-pack-peer-review-blocker-class-guide.md) — addon 给客户 / 平台交付 PromQL 规则包 (raw metric + recording rule + alert rule) 时 peer review 的 8 类 blocker checklist：字面错 / 混层归因 / 协议层硬约束被掩盖 / PromQL 语义口语化 / pending 分支漏 / query body 与预期值不自洽 / topology 维度漏 / GitHub-facing 署名残留 + closed 状态没贯穿读者最先看的段落。是 `addon-design-contract-review-during-xp-guide.md` 在规则包 / spec / 文档 review 场景的姐妹篇 +- [`addon-controller-diagnostic-pr-scope-guide.md`](addon-controller-diagnostic-pr-scope-guide.md) — controller 诊断-only PR 的边界：只为抓证据加日志时不默认进 main，先走临时分支 / release 分支 / patch image；证据闭合后再开正式修复 PR diff --git a/docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md b/docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md new file mode 100644 index 0000000..324b0ae --- /dev/null +++ b/docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md @@ -0,0 +1,84 @@ +# Controller Diagnostic PR Scope 指南 + +> **Audience**: KubeBlocks controller / DataProtection / Configure / Ops 工程师，以及 review 这些 PR 的同伴。 +> **Status**: draft +> **Applies to**: 只为排查问题而加日志、指标、事件或临时观测点的 controller 改动。 +> **Applies to KB version**: all +> **Affected by version skew**: yes — 诊断补丁通常只服务某个 release 现场或 patch image。 + +当 addon 测试卡在 controller 链路里，但证据还不足以写修复时，工程师常会先加诊断日志。这个文档解决一个边界问题：**诊断补丁不是正式修复**。它应该帮助下一轮测试抓证据，而不是默认合进 main。 + +## 先用白话理解这篇文档 + +如果一段代码只是为了"看清楚现场发生了什么"，它就不应该被当成产品修复。先用临时分支、release 分支、patch image 或 sideload 跑一轮，把证据抓回来。 + +等证据说明根因和修法后，再开真正的修复 PR。真正修复 PR 才考虑进 main。 + +## 适用场景 + +| 我在做什么 | 这篇 guide 怎么用 | +|---|---| +| 为卡住的 OpsRequest 补 queue 日志 | 走诊断补丁，不默认进 main | +| 为 Configure 卡住补 reconcile 入口日志 | 先服务当前复现和证据采集 | +| 为 DataProtection restore 补一次性状态打印 | 只证明现场路径，不替代修复 | +| 已经知道修法并改了行为 | 这不是诊断补丁，按正常修复 PR 走 | + +## 通用方法论 + +### 硬规则 + +1. **只加诊断信息，不改行为**：日志、事件、指标可以；排队、状态机、重试、删除、回滚语义不能变。 +2. **诊断-only PR 不默认进 main**：优先用临时分支、release 分支、本地 build、patch image、sideload 跑目标现场。 +3. **PR 标题和正文要写明范围**：写清楚 `diagnostic only` / `logging only`，并说明不会闭合根因。 +4. **证据回来后再决定是否修 main**：如果证据证明是产品 bug，再单独开修复 PR。 +5. **不要把分支级 CI 问题混进诊断 PR**：release 分支工具链红项要单独维护，不塞进日志补丁。 + +### 判断表 + +| 改动内容 | 归类 | 下一步 | +|---|---|---| +| 只补 `V(1)` 日志，帮助区分分支 | 诊断补丁 | 临时分支 / release 分支 / patch image | +| 补日志同时改变 retry / queue / status | 行为修复 | 写红测，开正式修复 PR | +| 为现网 release 复现加一次性日志 | 诊断补丁 | 不默认 cherry-pick 到 main | +| 修掉 nil deref / 错误状态 / 状态不收口 | 行为修复 | main PR + backport PR | + +### PR 正文最小模板 + +```markdown +Scope: diagnostic only. + +This PR adds logs for so the next run can distinguish: +- +- +- + +It does not change behavior: +- no queue/status/retry/delete semantics changed +- not a root-cause fix + +Validation: +- +- + +Next: +- build/sideload patch image for +- collect evidence in +``` + +## 与其他 doc / skill 的关系 + +- [`../../skills/autonomous-controller-development-loop/SKILL.md`](../../skills/autonomous-controller-development-loop/SKILL.md) 要求 controller agent 主动处理 PR、CI 和 addon handoff。本文补充的是"诊断补丁是否进 main"的边界。 +- [`../test/addon-patch-image-controller-active-verification-guide.md`](../test/addon-patch-image-controller-active-verification-guide.md) 说明 patch image 跑起来后，如何证明测试真的命中了目标 controller commit。 +- [`addon-github-submission-discipline-guide.md`](addon-github-submission-discipline-guide.md) 仍然适用于诊断 PR 的提交纪律。 + +## 案例附录 + +### OceanBase OpsRequest queue 日志 + +一个 release-1.0 PR 只给 OpsRequest queue / deletion / dequeue 加诊断日志。它用于下一轮 OceanBase 长跑时区分"没进队列"、"被已有 Running 操作挡住"、"已经在跑"、"出队没有命中 annotation"。 + +这类 PR 不改行为。它只服务当前证据采集，不需要再推一份 main PR。后续如果证据证明 queue 逻辑真的要改，再开正式修复 PR。 + +## 一句话总结 + +诊断补丁先用来抓证据，不默认进 main；证据指向真实修法后，再开正式修复 PR。 From 2a91e7c0880ad9cf0362478ea44979fb3ccc846e Mon Sep 17 00:00:00 2001 From: Wei Cao Date: Tue, 19 May 2026 12:38:05 +0800 Subject: [PATCH 2/2] docs: move controller guide to controller section --- docs/SKILL-INDEX.md | 5 +++-- docs/code-submission/README.md | 1 - docs/controller/README.md | 9 +++++++++ .../addon-controller-diagnostic-pr-scope-guide.md | 2 +- 4 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 docs/controller/README.md rename docs/{code-submission => controller}/addon-controller-diagnostic-pr-scope-guide.md (95%) diff --git a/docs/SKILL-INDEX.md b/docs/SKILL-INDEX.md index faca72a..783bc20 100644 --- a/docs/SKILL-INDEX.md +++ b/docs/SKILL-INDEX.md @@ -2,7 +2,7 @@ 这套文档面向 Addon 开发与测试工程师，采用渐进式披露的目录组织： -- 顶层：本索引列出 8 个领域，每个领域 1 行描述。 +- 顶层：本索引列出 9 个领域，每个领域 1 行描述。 - 中层：每个领域子目录的 `README.md` 列本领域所有 guide。 - 底层：guide 本身写方法论；引擎相关内容放在 `cases/` 下。 @@ -15,6 +15,7 @@ | [`design/`](design/README.md) | 设计 / 开发新 addon — ComponentDefinition、lifecycle action、bootstrap、role publish、switchover、TLS、reconfigure、probe、ParametersDefinition、controller crash resilience | `design/README.md` | | [`test/`](test/README.md) | 写 smoke / chaos / soak / regression 测试 — first blocker、bounded retry、evidence discipline、harness 三轨、baseline / intensity / parallel、fake server validation、ship-readiness validation | `test/README.md` | | [`troubleshoot/`](troubleshoot/README.md) | 运行期排障 — Ops/Restart 卡住、reconcile 诊断、chart vs KB schema skew、finalizer 死锁、stuck-resource cleanup、image-tag vs PR merge 边界 | `troubleshoot/README.md` | +| [`controller/`](controller/README.md) | KubeBlocks controller 开发经验 — DataProtection、Configure、Ops、诊断补丁、patch image、主线修复边界 | `controller/README.md` | | [`code-submission/`](code-submission/README.md) | GitHub 提交 / PR / merge / review 纪律 | `code-submission/README.md` | | [`agent-collab/`](agent-collab/README.md) | Agent 自我纪律 + 互相协作 — skill 推广、skill 清单治理、Slock 线程纪律、pre-escalation、wording calibration | `agent-collab/README.md` | | [`vcluster/`](vcluster/README.md) | IDC vcluster 测试环境 — bootstrap、syncer 资源、镜像策略、生命周期、未发布 controller patch 验证 | `vcluster/README.md` | @@ -46,4 +47,4 @@ ## 找不到合适入口？ -如果以上 8 个领域和 cases 都不直接匹配你的场景，从根 [`addon-autonomous-development-loop-guide.md`](addon-autonomous-development-loop-guide.md) 开始，那篇 guide 描述的工作循环会自然带你走到对应领域。 +如果以上 9 个领域和 cases 都不直接匹配你的场景，从根 [`addon-autonomous-development-loop-guide.md`](addon-autonomous-development-loop-guide.md) 开始，那篇 guide 描述的工作循环会自然带你走到对应领域。 diff --git a/docs/code-submission/README.md b/docs/code-submission/README.md index fc2d4f6..e123cd4 100644 --- a/docs/code-submission/README.md +++ b/docs/code-submission/README.md @@ -10,4 +10,3 @@ - [`addon-design-contract-review-during-xp-guide.md`](addon-design-contract-review-during-xp-guide.md) — XP / pair-programming 代码 review 阶段的 8 类设计契约级缺陷 checklist（silent fallback / 非空字段未强制 / 同 commit state 不连续 / sentinel 值传错误 / 条件清理状态枚举不穷尽 / NotFound 短路写入 / terminating vs absent / 运算符优先级） - [`addon-spec-field-zero-vs-unset-guide.md`](addon-spec-field-zero-vs-unset-guide.md) — Class 4 (sentinel value confusion) 在 spec field 上的展开：spec 零值 vs 字段不存在的反模式识别 + 4 种正确区分方法 + 验收路径与执行路径必须一致的修复口径 - [`addon-promql-rule-pack-peer-review-blocker-class-guide.md`](addon-promql-rule-pack-peer-review-blocker-class-guide.md) — addon 给客户 / 平台交付 PromQL 规则包 (raw metric + recording rule + alert rule) 时 peer review 的 8 类 blocker checklist：字面错 / 混层归因 / 协议层硬约束被掩盖 / PromQL 语义口语化 / pending 分支漏 / query body 与预期值不自洽 / topology 维度漏 / GitHub-facing 署名残留 + closed 状态没贯穿读者最先看的段落。是 `addon-design-contract-review-during-xp-guide.md` 在规则包 / spec / 文档 review 场景的姐妹篇 -- [`addon-controller-diagnostic-pr-scope-guide.md`](addon-controller-diagnostic-pr-scope-guide.md) — controller 诊断-only PR 的边界：只为抓证据加日志时不默认进 main，先走临时分支 / release 分支 / patch image；证据闭合后再开正式修复 PR diff --git a/docs/controller/README.md b/docs/controller/README.md new file mode 100644 index 0000000..bae85fe --- /dev/null +++ b/docs/controller/README.md @@ -0,0 +1,9 @@ +# controller — KubeBlocks controller 开发经验 + +这个目录放 KubeBlocks controller / DataProtection / Configure / Ops 等 controller 侧的开发经验。 + +这里的文档只写 controller 通用规则。具体 addon、引擎、测试现场结果放到对应 `cases/` 目录。 + +## Guides + +- [`addon-controller-diagnostic-pr-scope-guide.md`](addon-controller-diagnostic-pr-scope-guide.md) — controller 诊断-only PR 的边界：只为抓证据加日志时不默认进 main，先走临时分支 / release 分支 / patch image；证据闭合后再开正式修复 PR。 diff --git a/docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md b/docs/controller/addon-controller-diagnostic-pr-scope-guide.md similarity index 95% rename from docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md rename to docs/controller/addon-controller-diagnostic-pr-scope-guide.md index 324b0ae..7b58e51 100644 --- a/docs/code-submission/addon-controller-diagnostic-pr-scope-guide.md +++ b/docs/controller/addon-controller-diagnostic-pr-scope-guide.md @@ -69,7 +69,7 @@ Next: - [`../../skills/autonomous-controller-development-loop/SKILL.md`](../../skills/autonomous-controller-development-loop/SKILL.md) 要求 controller agent 主动处理 PR、CI 和 addon handoff。本文补充的是"诊断补丁是否进 main"的边界。 - [`../test/addon-patch-image-controller-active-verification-guide.md`](../test/addon-patch-image-controller-active-verification-guide.md) 说明 patch image 跑起来后，如何证明测试真的命中了目标 controller commit。 -- [`addon-github-submission-discipline-guide.md`](addon-github-submission-discipline-guide.md) 仍然适用于诊断 PR 的提交纪律。 +- [`../code-submission/addon-github-submission-discipline-guide.md`](../code-submission/addon-github-submission-discipline-guide.md) 仍然适用于诊断 PR 的提交纪律。 ## 案例附录