mirror of https://lore.kernel.org/lkml/
 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	[flat|nested] 2+ messages in thread

* Re: [PATCH] btrfs: add a per-subsystem agent file
  2026-11-17  5:58 [PATCH] btrfs: add a per-subsystem agent file Qu Wenruo
@ 2026-11-17  9:37 ` Leon Romanovsky
  0 siblings, 0 replies; 2+ messages in thread
From: Leon Romanovsky @ 2026-11-17  9:37 UTC (permalink / raw)
  To: Qu Wenruo; +Cc: linux-btrfs, workflows, linux-kernel, linux-doc

On Tue, Nov 17, 2026 at 04:28:18PM +1030, Qu Wenruo wrote:
> 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.

It looks like general descriptions to me and can fit other subsystems too.

Thanks

> 
> 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] 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

all inboxes | Powered by JetHome®