From: Leon Romanovsky <leon@kernel.org>
To: Qu Wenruo <wqu@suse.com>
Cc: linux-btrfs@vger.kernel.org, workflows@vger.kernel.org,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org
Subject: Re: [PATCH] btrfs: add a per-subsystem agent file
Date: Tue, 17 Nov 2026 11:37:42 +0200 [thread overview]
Message-ID: <20261117093742.GC124972@unreal> (raw)
In-Reply-To: <df1c1fa031ba7e66486348dc37d1a7be53c18e43.1794894953.git.wqu@suse.com>
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
>
>
prev parent reply other threads:[~2026-11-17 12:48 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-17 5:58 [PATCH] btrfs: add a per-subsystem agent file Qu Wenruo
2026-11-17 9:37 ` Leon Romanovsky [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261117093742.GC124972@unreal \
--to=leon@kernel.org \
--cc=linux-btrfs@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=workflows@vger.kernel.org \
--cc=wqu@suse.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox