Skip to content

docs(docs): add independent-review developer guide (recommended practice)#1341

Open
jfeng18 wants to merge 3 commits into
alibaba:mainfrom
jfeng18:docs/independent-review
Open

docs(docs): add independent-review developer guide (recommended practice)#1341
jfeng18 wants to merge 3 commits into
alibaba:mainfrom
jfeng18:docs/independent-review

Conversation

@jfeng18

@jfeng18 jfeng18 commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator

What

新增 docs/developer-guide/{en,zh}/independent-review.md——一份推荐的、可选的 anolisa 代码审查 checklist(双语)。它把"不继承作者上下文的独立审查"这套纪律,加上 anolisa 多语言多组件特有的审查角度,沉淀成一份可照着做的清单。

Why

CI 能抓机械工具可证明的东西(fmt / clippy / test / coverage / commitlint);单个人工 reviewer 能抓更多,但作者自审时会带着作者的思维框架,审别人时又受限于一个人的盲区。这份 doc 针对的是两者之间的缝隙——linter 和单个 reviewer 都不可靠覆盖的结构 / 正确性 / 安全 / 跨组件问题,尤其是 anolisa 特有、CI 结构上抓不到的角度:

  • eBPF verifier 与内核安全(*.bpf.c 无自动测试门禁)
  • 架构 / 环境矩阵(arch × kernel × container,x86 CI 对 aarch64 页大小类问题天然盲)
  • FFI / cbindgen ABI 边界(header/签名/示例漂移是静默高危)
  • 跨组件契约(agentsight ↔ cosh ↔ anolisa-cli ↔ genai storage)
  • agent 安全(sec-core、特权写、不可信输入)
  • 打包 / 分发正确性(*.spec.in / component.toml 不被 code-test CI 覆盖)

和现有机制的关系

  • 补充,不替代:人工 CODEOWNERS review + CI 绿仍是强制门禁。
  • 非强制、非 CI gate:CI 证明不了一次 review pass 是否跑过,且对不使用 agent 工具的贡献者不公平。定位是 author-side 的提 PR 前自检 + reviewer-side 的辅助。
  • 工具中性:不用任何 agent 也能当作纯人工 review checklist;对 review AI agent 同样适用。

想请教落位(cc @casparant

这是一份 cross-cutting 的方法论 doc,我暂时放在 developer-guide/{en,zh}/ 顶层。但 specs/documentation-standard.md#1333)里 developer-guide 是"按组件组织",没有为 cross-cutting 的过程类 doc 明确预留位置。请你定该放哪更合适——developer-guide 顶层,还是 CONTRIBUTING / 某个 process 区,或别的?我照调。

Testing

  • 纯文档改动,无代码、无 CI 逻辑变化。
  • en / zh 语义等价,cross-ref 头互指。
  • 无 E2E(文档)。

…ice)

Bilingual (en/zh) recommended review checklist under docs/developer-guide/.
Captures the zero-context independent-review discipline plus anolisa-specific
review angles (eBPF verifier, arch matrix, FFI/cbindgen, cross-component
contract, agent security, packaging). Recommended and optional — complements
human CODEOWNERS review + CI, not a gate.
@jfeng18 jfeng18 requested a review from casparant as a code owner July 5, 2026 05:53
@github-actions github-actions Bot added the scope:documentation ./docs/|./*.md|./NOTICE label Jul 5, 2026
jfeng18 added 2 commits July 5, 2026 14:31
- verify the PR's claimed mechanism against real code, don't trust its
  abstract terms (e.g. "YAML injection" when there is no YAML parser)
- withdraw a finding that doesn't hold up on verification
Keep the discipline abstract; avoid citing a specific incident/PR.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

scope:documentation ./docs/|./*.md|./NOTICE

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant