* [PATCH] btrfs: add a per-subsystem agent file
@ 2026-11-17 5:58 Qu Wenruo
0 siblings, 0 replies; only message 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 [flat|nested] only message in thread
only message in thread, other threads:[~2026-11-17 5:58 UTC | newest]
Thread overview: (only message) (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
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®