docs(code-submission): add PromQL rule pack peer review 8-class blocker guide#222
Conversation
|
Round-1 focused review: HOLD. Reviewed latest Blockers:
Accepted in this pass:
XP 8-class walkthrough: Class 1/2 issue is in doc contract wording, not code. The main blockers are Class 2-style contract enforcement for documentation links and addon-docs-writing readability/term-expansion contract. Class 5-8 no runtime/cleanup risk in this doc/static scope. Boundary: doc/static review only. I did not run live evaluate or validate any Oracle runtime evidence. |
weicao
force-pushed
the
weicao/promql-rule-pack-peer-review-blocker-class-guide
branch
from
ab2b07f to
584514f
Compare
|
Round-2 focused review: HOLD. Reviewed latest Checks I ran:
The two doc-body blockers from round 1 are mostly closed. Remaining blockers are GitHub-facing wrapper drift:
Accepted:
Nit, not blocking:
Boundary: doc/static review only. I did not run live PromQL evaluate or runtime validation. |
weicao
force-pushed
the
weicao/promql-rule-pack-peer-review-blocker-class-guide
branch
from
584514f to
116985b
Compare
|
Round-3 focused review: PASS. Reviewed latest Checks I ran:
Accepted:
Non-blocking nit remains:
Boundary: doc/static focused review only. I did not run live PromQL evaluate or runtime validation. |
weicao
force-pushed
the
weicao/promql-rule-pack-peer-review-blocker-class-guide
branch
from
116985b to
76c23b4
Compare
|
Post-PASS nit verification OK on Checked the force-push after round-3 PASS:
This does not change the round-3 PASS verdict. Boundary remains doc/static review only; no live PromQL evaluate/runtime validation. |
…er guide
新增 `docs/code-submission/addon-promql-rule-pack-peer-review-blocker-class-guide.md`,
把 addon 给客户/平台交付 PromQL 规则包 (raw metric + recording
rule + alert rule) 时 peer review 抓得到 / 抓不到的八类 blocker 写成
checklist, 让规则包交付前就锁在 review 阶段。
八类 blocker:
1. 字面错 (mental-run + raw dump 双向 grep 之前不能写)
2. 混层归因 (现象归因到不同 evidence 层)
3. 协议层硬约束被"补完"假设掩盖 (fork 万能反模式)
4. PromQL 语义口语化 ("LHS 保留" 不准确)
5. pending 分支漏列 (backlog 项的下游 alert 行为不标 pending)
6. query body 与预期值不自洽 (改 query 没回头 mental-run)
7. topology 维度漏拆 (PoC same-cluster vs production cross-cluster)
8. GitHub-facing 署名残留 + closed 状态没贯穿读者最先看的段落
每一类给一句话定义 + reviewer 挡法 + 修法。文末给 reviewer
checklist (一遍跑完八类) + 反模式速查表。
主体 engine-neutral; 引擎相关 (Oracle DG/DR) 实证案例 cross-link 到
`docs/cases/oracle/oracle-dg-dr-promql-rule-pack-sprint2-case.md`
`## 一句话总结` 段 (跨 PR 依赖: 先合 PR #221 再合本 PR, 否则 main
上的 cross-link 会断)。
跟 `addon-design-contract-review-during-xp-guide.md` (代码 review 8 类)
互为姐妹篇 — 同一套 XP review 方法论, 两种不同 domain。
来源: Skyworth PoC Sprint 2 Oracle Data Guard / DR 规则包交付迭代
沉淀的真实 blocker 类型, 输出通用 checklist 给其他 addon 团队消费。
按 `addon-docs-writing` skill 模板写: frontmatter + 第一段问题陈述 +
先用白话理解 + 术语速查 (14 个术语首次出现展开) + 适用场景表 + 通用
方法论 (八类定义 + reviewer checklist + 反模式表) + 与其他 doc/skill
关系 (cross-link design-contract-review-during-xp + docs-writing-guide
+ github-submission-discipline) + 案例附录 (Oracle case cross-link) +
一句话总结。
行数 167 (高于通用 single-team guide ≤150 行起步指引), 例外口径:
跨 addon 团队消费场景需要术语首次出现展开 + 第一段拆短, 突破 17 行。
weicao
force-pushed
the
weicao/promql-rule-pack-peer-review-blocker-class-guide
branch
from
76c23b4 to
9a3eab4
Compare
weicao
deleted the
weicao/promql-rule-pack-peer-review-blocker-class-guide
branch
…se (#226) 新增 docs/cases/oracle/oracle-dg-dr-alert-template-drift-path-a-fix-case.md (250 行), 沉淀 alert template `{{ $labels.X }}` 字面引用 metric 不携带的 label 时渲染空字符串这一 UX 字面错的 Path A doc-spec 层修法。 具体场景: addon 给客户/平台交付 Prometheus alert template 时, 在 description / labels / summary 字段写了 `{{ $labels.thread_id }}` 或 `{{ $labels.db_unique_name }}` 这种 label 插值, 但实际触发告警的 metric 不携带这个 label。Prometheus / vmalert 不会拦截, 静悄悄渲染成空字符串。 告警卡片上出现"DG 备库 (, thread )"这样的半截描述, 客户值班看见会问 "是不是坏了", 信任度被磨掉。 修法分两条路: - Path A (doc-spec 层短期修, 本 case 主体): 改 alert template 字面, 全局 default labels 块拆 per-rule, 只在 metric 携带的 rule 上 promote; description 字面只引用 metric 携带的 label; pending 分支显式标 (backlog ID + spec 描述 + 落地后要改成什么)。 - Path B (SQL 层长期修, 排 Sprint 3+ backlog): fork exporter binary, 改 SQL probe 加 select 把 label 补齐到 raw metric 上。 主体 engine-neutral: - 5 条硬规则 (mental-run / 全局 default 只放每条都有的 / per-rule labels 只放 metric 携带的 promote / mental-run + UI 抽查 verify / pending 显式标) - per-rule label promotion 决策树 (3 步) - pending 分支标记三件信息口径 - 6 行反模式表 (label drift / 全局默认放部分 metric label / fork 万能 反模式 / recording rule LHS 自动保留误解 / pending 不标 / 不 mental-run) 案例附录 (A.1-A.9, Oracle Data Guard / Disaster Recovery 具体例子): - 五项 lock 不变 (跟 v0.2 final 字面对齐) - 6 raw metric label 集 (含 replication_lag_seconds 表载 vs raw scrape drift 备注) - v0.2 final → v0.3 字面 diff 表 (12 行 diff 类别) - §4 全局 default labels v0.3 字面 (删 db_unique_name 行) - Rule 1/2/9/10 description v0.3 字面 (删 `, thread {{ thread_id }}`) - Rule 5/12 per-rule labels v0.3 字面 (加 thread_id promotion) - Rule 7/8 pending B1-b 注释 v0.3 字面 - §6 e2e 验证项 6 (AlertManager UI 抽查 db_unique_name / thread_id 非空 + Rule 4/6/13 无空字符串残留) - Sprint 3 W1+ batch 待 trigger 表 按 addon-docs-writing skill 模板: frontmatter + 第一段问题陈述 (本 case 解决什么场景) + `## 先用白话理解这篇文档` (4 段) + `## 术语速查` (10 个术语 first-use expand) + `## 适用场景` 表 + `## 通用方法论` (硬规则 + 决策树 + pending 口径 + 反模式表) + `## 与其他 doc / skill 关系` (cross-link PR #221 case body + PR #222 8 类 blocker guide + design-contract-review-during-xp + addon-docs-writing skill) + `## 案 例附录` + `## 一句话总结`。 跨 PR 依赖: 本 PR 跟 PR #221 (Sprint 2 case body) + PR #222 (8 类 peer review blocker class guide 同期 OPEN。本 PR cross-link PR #221 §6.5 Path A vs Path B 路径选择 + §10 backlog row B3 owner 路由; 合并顺序 建议先 #221 (本 PR 的 cross-link 依赖), 再 #222 / 本 PR (这两个独立)。 来源: Skyworth PoC Sprint 2 Oracle DG/DR 规则包交付 P1-E (alert template label drift, 9 条 rule definite affected) 修法落地。Emma (KubeBlocks Enterprise) P1-E scope 收敛后 audit 确认 fixture JSON 字面 0 change, Path A 物理位置 = Oracle Addon 自己 workspace v0.2 final spec doc; Emma 倾向 (c) PR-ify 一步到位 + GitHub byte-level diff view 比 inline paste 更稳 → 本 PR。Cindy 22:27 patrol 提的案例沉淀方向对齐。 EOF ) Co-authored-by: Ava <ava@apecloud.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
1 participant
Summary
新增
docs/code-submission/addon-promql-rule-pack-peer-review-blocker-class-guide.md(167 行), 把 addon 给客户/平台交付 PromQL 规则包 (raw metric + recording rule + alert rule) 时 peer review 抓得到 / 抓不到的八类 blocker 写成 checklist, 让规则包交付前就锁在 review 阶段。PR 依赖 (合并顺序)
本 PR 案例附录 cross-link 到 PR #221 (
docs/cases/oracle/oracle-dg-dr-promql-rule-pack-sprint2-case.md)。先合 PR #221, 再合本 PR, 否则 main 上的 cross-link 会断。八类 blocker
on(...)输出 label semantics与既有 doc 关系
addon-design-contract-review-during-xp-guide.md(代码 review 8 类) 互为姐妹篇 — 同一套 XP review 方法论, 两种不同 domain (代码 vs 规则包 / spec / 文档)addon-docs-writing-guide.md本文产物即模板 instance — 自身按模板写addon-github-submission-discipline-guide.md共同 source (类 8 署名残留)来源
Skyworth PoC Sprint 2 Oracle Data Guard / DR 规则包交付迭代沉淀的真实 blocker 类型, 输出通用 checklist 给其他 addon 团队消费; 实证案例见
oracle-dg-dr-promql-rule-pack-sprint2-case.md## 一句话总结段 (PR #221, 先合 #221 再合本 PR)。Test plan
addon-docs-writingskill self-check 3Q passed (frontmatter / 先用白话理解 / 适用场景 / 与其他 doc/skill 关系 / 一句话总结)on(...)/LHS/group_left/count by(...)/topology/mental-run/by-design/backlog/PoC) 首次出现展开Boundary