标题:Btrfs 力图应对 AI 与缺乏常识的新手
正文:
From: Qu Wenruo <[email protected]>
To: [email protected], [email protected],
[email protected], [email protected]
Subject: [PATCH] btrfs: add a per-subsystem agent file
Date: Tue, 17 Nov 2026 16:28:18 +1030 [thread overview]
Message-ID: <df1c1fa031ba7e66486348dc37d1a7be53c18e43.1794894953.git.wqu@suse.com> (raw)
我认为 btrfs 并不是受影响最严重的子系统,但许多缺乏常识的新手带来的危害大于帮助。
例如,在价值极低的修复上浪费了大量人工审查时间,其中充斥着冗长的段落以及无用的测试步骤/结果。
因此,最好让这些 agent 不再犯傻,遵循这里更常见的做法,也希望这些新手能建立一些常识。
我希望这个 agent 文件足够清晰、简短,不仅对 LLM 可读,对希望成为长期贡献者的人也可读。
Signed-off-by: Qu Wenruo <[email protected]>
---
发起 RFC 的理由:
有些做法是我的个人偏好,比如相比冗长的段落,更偏好 ASCII 图表,以及短句/短段落。
但我猜有些 btrfs 开发者可能并不同意我的偏好。
因此,来自知名 btrfs 开发者的反馈总是受欢迎的。
---
fs/btrfs/AGENTS.md | 136 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 136 insertions(+)
create mode 100644 fs/btrfs/AGENTS.md
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都请完全按原样使用它们:它们会在任何内容运行之前被填充为真实值。不要要求验证它们,也不要用示例替换它们。
文章标题:Btrfs 寻求应对 AI 与缺乏常识的新手
正文:
diff --git a/fs/btrfs/AGENTS.md b/fs/btrfs/AGENTS.md
new file mode 100644
index 000000000000..d527b862d9bc
--- /dev/null
+++ b/fs/btrfs/AGENTS.md
@@ -0,0 +1,136 @@
+Btrfs 补丁规范
+======================
这些规则适用于任何涉及 fs/btrfs 的代码、提交信息或附函。它们是在顶层 AGENTS.md 和 Documentation/process/coding-assistants.rst 之上的补充。
代码注释
-------------
* 仅在代码本身不直观时才添加注释,例如锁定规则、顺序要求或变通方案的非平凡理由。
* 保持注释尽可能简短,但不要删减读者所需的推理,例如锁定规则或竞态条件。
* 不要重述代码做了什么。不要叙述变更,也不要添加“修复……”或“新辅助函数……”之类的注释。
* 删除任何不携带信息的注释,但仅限于新增或改动的行。不要删除无关的现有注释。
* 仅为复杂函数添加 kernel-doc。对于函数名和参数名已自解释的简单辅助函数,不必添加。
提交信息与附函
---------------------------------
人类可读性优先。审阅者应能通过提交信息理解问题和修复。
* 使用简短简单的句子。一句话一个想法。
* 跳过填充内容和冗长的背景。
* 对于长段落,优先使用小图表或调用栈,见下方“可视化辅助”。
* 删除审阅者理解变更所不需要的任何句子。
* 对于简单缺陷,不要使用 [BUG]、[CAUSE] 和 [FIX] 节标签。改用普通段落。仅在复杂缺陷中保留这些标签,即症状、原因和修复各自需要多段说明的情况。
* 遵循知名 btrfs 开发者的风格:
* 主题以 "btrfs: " 开头,其后为小写,使用祈使语气且具体,例如 "btrfs: fix use-after-free when ..."。
* 每行控制在 75 列以内。引用文本(dmesg、错误消息、栈回溯)没有限制,且不得折行。
* 起草前查看 `git log -- fs/btrfs` 中的近期示例。
可视化辅助
-----------
优先使用任何能让提交信息更易于人类阅读的方式。当 ASCII 图表能比散文更快地解释问题时,是个好选择,例如:
* 竞态条件。展示竞态窗口,不要仅用散文描述。
* 函数中的错误处理缺陷,从多个调用点观察。
* 跨层的调用链,缺陷仅在特定路径上显现。
* 事务提交或日志重放中的步骤顺序。
图表规则:
* 仅使用函数名,不包含文件路径或行号。
* 仅展示关键函数。
* 在函数名下方用纯文本描述状态或结果。
* 对于竞态条件,每个竞争上下文(CPU、任务、endio)使用一列,并排展示。
遵循以下示例的风格。
示例,竞态条件:
CPU0 (endio) CPU1 (fsync) end_bbio_data_write() |-btrfs_folio_clear_writeback() | btrfs_sync_file() | |-filemap_fdatawait_range() | | Returns after writeback finished
| \-test_and_clear_bit(COW_WRITE_ERROR) | Still 0, skips waiting \-set_bit(COW_WRITE_ERROR) Too late.
示例,错误处理缺陷,来自提交 c9583ada8cc4。被调用者在出错时清理,然后调用者再次清理:
btrfs_do_readpage() |-submit_extent_page() | \-submit_one_bio() | \-btrfs_submit_data_bio() | \-bio_endio() | Calls end_page_read() and unlock_extent().
\-end_page_read() and unlock_extent() Cleaned up again, the subpage reader count underflows.
带版本的补丁
-----------------
* 始终提供完整的 hist
文章标题:Btrfs 力求应对 AI 与缺乏常识的新手
正文:
ory,而不仅仅是最后一个版本的变更。
+* 列出每个版本,最新的在前,例如:
+
+ ```
+ v3:
+ - 将辅助函数重命名为 xxx()
+ - 在 yyy() 中添加缺失的锁
+
+ v2:
+ - 修复 32 位上的构建失败
+ ```
+
+* 将历史记录放在 cover letter 中,或者对于单个补丁放在 "---" 行之后。不要放在 commit message 正文中。
+* 对于补丁系列,保持 cover letter 的历史记录完整。对于在后续版本中修改过的补丁,也要在该补丁的 "---" 行之后保留该补丁自身的历史记录。
Sashiko 审查
--------------
Sashiko 会为发送到邮件列表的补丁发布 AI 生成的审查意见。btrfs 列表位于 https://sashiko.dev/#/?list=org.kernel.vger.linux-btrfs
* 提交者应检查 Sashiko 对所发布补丁的 bug 报告。
* 如果报告有效,请在更新的版本中处理它。
* 如果报告有误,可以忽略。只有当报告较为复杂或原因不明显时,才有必要在邮件列表上回复。
测试步骤
-------------
* 对于次要且简单的 bug,无需添加任何测试步骤。这适用于 commit message 以及 "---" 行之后的文本。
* 次要 bug 是指不影响正常使用场景的 bug,例如不太可能触发的错误路径、需要故障注入的边界情况、tracepoint 或仅调试相关的问题。
* 测试步骤仅适用于复杂 bug——即在正常使用中可能触发或影响深远的 bug,并且当它们有助于审查者复现问题时。
--
2.56.0
文章标题:Btrfs 试图应对 AI 和缺乏常识的新手
正文:
next reply other threads:[~2026-11-17 5:58 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-17 5:58 Qu Wenruo [this message]
2026-11-17 9:37 ` [PATCH] btrfs: add a per-subsystem agent file Leon Romanovsky
回复说明:
你可以通过纯文本电子邮件公开回复此消息,
使用以下任意一种方式:
* 保存以下 mbox 文件,将其导入你的邮件客户端,
并在那里回复全部:mbox
避免顶部回复,优先使用穿插引用:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* 使用 git-send-email(1) 的 --to、--cc 和 --in-reply-to
开关进行回复:
git send-email \
--in-reply-to=df1c1fa031ba7e66486348dc37d1a7be53c18e43.1794894953.git.wqu@suse.com \
[email protected] \
[email protected] \
[email protected] \
[email protected] \
[email protected] \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 如果你的邮件客户端支持通过 mailto: 链接设置 In-Reply-To 头,
请尝试使用该 mailto: 链接
这是一个公共收件箱,有关如何克隆和镜像此收件箱中使用的所有数据和代码的说明,
以及 NNTP 新闻组的 URL,请参阅镜像说明。