The Linux Kernel Mailing List
 help / color / mirror / Atom feed
* [PATCH] btrfs: add a per-subsystem agent file
@ 2026-11-17  5:58 Qu Wenruo
  2026-11-17  9:37 ` Leon Romanovsky
  0 siblings, 1 reply; 2+ messages in thread
From: Qu Wenruo @ 2026-11-17  5:58 UTC (permalink / raw)
  To: linux-btrfs, workflows, linux-kernel, linux-doc

I believe btrfs is not the most affected sub-system, but a lot of
newbies without common senses are doing more harm than help.
E.g. wasting a lot of human review time on very low value fixes, filled
with long paragraphs and useless test steps/results.

So it would be better to let those agents to stop being stupid and
follow the more common practices here, and hopefully those newbies can
build some common sense.

I hope the agent file is clear and short enough, that is not only
readable for LLMs, but also for humans who want to be long term
contributers.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
Reason for RFC:

Some practices are my personal preferences, like prefer ASCII charts
over long paragraphs, and short sentences/paragraphs.

But I guess some of btrfs developers may not even agree on my
preferences.

Thus feed back from well known btrfs developers are always appreciated.
---
 fs/btrfs/AGENTS.md | 136 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 fs/btrfs/AGENTS.md

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 patch guidelines
+======================
+
+These rules apply to any code, commit message or cover letter touching
+fs/btrfs. They come on top of the top-level AGENTS.md and
+Documentation/process/coding-assistants.rst.
+
+Code comments
+-------------
+
+* Add a comment only when the code is not obvious by itself, e.g. a locking
+  rule, an ordering requirement or a non-trivial reason for a workaround.
+* Keep it as short and simple as possible, but do not cut the reasoning a
+  reader needs, e.g. for locking rules or races.
+* Do not restate what the code does. Do not narrate the change, and do not
+  add comments like "fix for ..." or "new helper to ...".
+* Remove any comment that does not carry information, but only in the lines
+  being added or touched. Do not drop unrelated existing comments.
+* Add kernel-doc only for complex functions. Do not bother for simple helpers
+  whose function and parameter names are self-explaining.
+
+Commit messages and cover letters
+---------------------------------
+
+Human readability comes first. A reviewer should be able to understand the
+problem and the fix from the message.
+
+* Use short and simple sentences. One idea per sentence.
+* Skip filler and long background.
+* Prefer a small chart or call trace over a long paragraph, see "Visual aids"
+  below.
+* Drop any sentence the reviewer does not need to understand the change.
+* Do not use the [BUG], [CAUSE] and [FIX] section tags for simple bugs. Write
+  plain paragraphs instead. Keep the tags only for complex bugs, where the
+  symptom, the cause and the fix each need several paragraphs.
+* Follow the style of well-known btrfs developers:
+  * The subject starts with "btrfs: ", is lower case after that, and is
+    imperative and specific, e.g. "btrfs: fix use-after-free when ...".
+  * Keep lines within 75 columns. Quoted text (dmesg, error messages, stack
+    traces) has no limit and must not be folded.
+  * Check `git log -- fs/btrfs` for recent examples before drafting.
+
+Visual aids
+-----------
+
+Prefer anything that makes the message easier for a human to read. An ASCII
+chart is a good choice when it explains the problem faster than prose, e.g.:
+
+* A race. Show the race window, do not describe it in prose only.
+* An error handling bug in a function, seen from several call sites.
+* A call chain across layers, where the bug only shows on a certain path.
+* The order of steps in a transaction commit or a log replay.
+
+Chart rules:
+
+* Function names only, no file paths or line numbers.
+* Show only the functions that matter.
+* Describe a state or outcome with plain text under the function name.
+* For a race, use one column per racing context (CPU, task, endio), side by
+  side.
+
+Follow the style of the examples below.
+
+Example, a race:
+
+```
+ 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.
+```
+
+Example, an error handling bug, from commit c9583ada8cc4. The callee cleans up
+on error, then the caller cleans up again:
+
+```
+ 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.
+```
+
+Versioned patches
+-----------------
+
+* Always provide the full history, not only the changes of the last version.
+* List every version, newest first, e.g.:
+
+  ```
+  v3:
+  - Rename the helper to xxx()
+  - Add a missing lock in yyy()
+
+  v2:
+  - Fix the build failure on 32-bit
+  ```
+
+* Put the history in the cover letter, or after the "---" line for a single
+  patch. Do not put it in the commit message body.
+* For a series, keep the cover letter history complete. For a patch changed
+  in a later version, also keep that patch's own history after its "---" line.
+
+Sashiko review
+--------------
+
+Sashiko posts AI-generated review for patches sent to the mailing list. The
+btrfs list is at https://sashiko.dev/#/?list=org.kernel.vger.linux-btrfs
+
+* The submitter should check Sashiko for bug reports on the posted patches.
+* If a report is valid, address it in a newer version.
+* If a report is wrong, it can be ignored. A reply on the mailing list only
+  makes sense when the report is complex or the reason is not obvious.
+
+Testing steps
+-------------
+
+* For minor and simple bugs, there is no need to add any testing steps. This
+  applies to the commit message and to the text after the "---" line.
+* A minor bug is one that does not affect normal use cases, e.g. an
+  unlikely error path, a corner case that needs fault injection, a tracepoint
+  or a debug-only problem.
+* Testing steps are only appropriate for a complex bug that can be hit in
+  normal use or have a deep impact, and also when they help the reviewer to
+  reproduce it.
-- 
2.56.0


^ permalink raw reply related	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2026-11-17 12:48 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-17  5:58 [PATCH] btrfs: add a per-subsystem agent file Qu Wenruo
2026-11-17  9:37 ` Leon Romanovsky

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox